package com.zb.mom.ww.mxgateway.client;

import mxaccess_gateway.v1.MxaccessGateway.MxStatusCategory;
import mxaccess_gateway.v1.MxaccessGateway.MxStatusProxy;
import mxaccess_gateway.v1.MxaccessGateway.MxStatusSource;

/**
 * Helpers for inspecting {@link MxStatusProxy} values returned by the gateway.
 *
 * <p>An {@code MxStatusProxy} mirrors the MXAccess COM {@code MXSTATUS_PROXY}
 * struct. Per the wire contract, {@code category} is the authoritative verdict:
 * an entry succeeds only when its category is
 * {@code MX_STATUS_CATEGORY_OK}. The {@code success} member carries the raw
 * 16-bit COM value verbatim for diagnostics and is not a boolean, so it never
 * decides success or failure.
 */
public final class MxStatuses {
    private MxStatuses() {
    }

    /**
     * Returns whether the supplied status proxy reports success.
     *
     * <p>A {@code null} status is success because nothing was reported. A
     * present entry whose category is {@code MX_STATUS_CATEGORY_UNSPECIFIED}
     * is a failure: the worker always maps a category, so an unmapped one is
     * not proven OK.
     *
     * @param status the status proxy, may be {@code null}
     * @return {@code true} if {@code status} is {@code null} or its category is
     *         {@code MX_STATUS_CATEGORY_OK}, {@code false} otherwise
     */
    public static boolean succeeded(MxStatusProxy status) {
        return status == null || status.getCategory() == MxStatusCategory.MX_STATUS_CATEGORY_OK;
    }

    /**
     * Wraps a raw {@link MxStatusProxy} in an accessor view that exposes its
     * fields with idiomatic Java getters.
     *
     * @param status the raw status proxy
     * @return a view backed by {@code status}
     */
    public static MxStatusView view(MxStatusProxy status) {
        return new MxStatusView(status);
    }

    /**
     * Idiomatic-Java accessor view over a raw {@link MxStatusProxy}.
     *
     * @param raw the underlying status proxy this view delegates to
     */
    public record MxStatusView(MxStatusProxy raw) {
        /**
         * Returns the raw {@code success} member exactly as MXAccess reported
         * it. This is a diagnostic value, not a verdict — use
         * {@link MxStatuses#succeeded(MxStatusProxy)} to decide success.
         *
         * @return the raw success member
         */
        public int success() {
            return raw.getSuccess();
        }

        /**
         * Returns the high-level status category.
         *
         * @return the status category enum value
         */
        public MxStatusCategory category() {
            return raw.getCategory();
        }

        /**
         * Returns which subsystem detected the status.
         *
         * @return the detection source enum value
         */
        public MxStatusSource detectedBy() {
            return raw.getDetectedBy();
        }

        /**
         * Returns the detail code accompanying the status.
         *
         * @return the raw detail code
         */
        public int detail() {
            return raw.getDetail();
        }

        /**
         * Returns the raw, unmapped category code from MXAccess.
         *
         * @return the raw category integer
         */
        public int rawCategory() {
            return raw.getRawCategory();
        }

        /**
         * Returns the raw, unmapped detection-source code from MXAccess.
         *
         * @return the raw detection-source integer
         */
        public int rawDetectedBy() {
            return raw.getRawDetectedBy();
        }

        /**
         * Returns the diagnostic text supplied by MXAccess, if any.
         *
         * @return the diagnostic message, possibly empty
         */
        public String diagnosticText() {
            return raw.getDiagnosticText();
        }
    }
}
