/*_############################################################################
  _##
  _##  SNMP4J-Agent 3 - UnresolvedReference.java
  _##
  _##  Copyright (C) 2005-2026  Frank Fock (SNMP4J.org)
  _##
  _##  Licensed under the Apache License, Version 2.0 (the "License");
  _##  you may not use this file except in compliance with the License.
  _##  You may obtain a copy of the License at
  _##
  _##      http://www.apache.org/licenses/LICENSE-2.0
  _##
  _##  Unless required by applicable law or agreed to in writing, software
  _##  distributed under the License is distributed on an "AS IS" BASIS,
  _##  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  _##  See the License for the specific language governing permissions and
  _##  limitations under the License.
  _##
  _##########################################################################*/

package org.snmp4j.agent.io.prop;

import org.snmp4j.smi.OctetString;

/**
 * An {@code UnresolvedReference} represents a configured variable value that references another
 * variable or object instance (using the {@code {$name}} / {@code ${name}} syntax of the
 * {@link PropertyMOInput} format) which could not be resolved to an actual value &mdash; typically
 * because the configuration is inspected statically, without a running agent to supply the
 * referenced instance value.
 * <p>
 * Instead of dropping such a value (which would lose information), the reference token is preserved
 * so that tools building a MIB tree from a configuration can display <em>which</em> instance the
 * value would have been taken from at runtime.
 * <p>
 * The class extends {@link OctetString} (and therefore is a fully usable {@link org.snmp4j.smi.Variable})
 * so that it can flow through the {@link PropertyMOInput} parsing pipeline unchanged: its octets are
 * the UTF-8 bytes of the reference token, which keeps any downstream sub-index conversion
 * deterministic. Consumers that want to treat it specially can test with {@code instanceof}.
 *
 * @author SNMP4J.org
 * @version 3.9.2
 * @since 3.9.2
 */
public class UnresolvedReference extends OctetString {

    private static final long serialVersionUID = 1L;

    private final String reference;

    /**
     * Creates a new unresolved reference for the given reference token.
     *
     * @param reference
     *    the name or dotted instance OID of the variable that the configuration referenced,
     *    e.g. {@code "1.3.6.1.6.3.10.2.1.1.0"}. A {@code null} value is treated as an empty reference.
     */
    public UnresolvedReference(String reference) {
        super(reference == null ? "" : reference);
        this.reference = (reference == null) ? "" : reference;
    }

    /**
     * Returns the raw reference token (without any surrounding {@code {$...}} decoration).
     *
     * @return the configured reference.
     */
    public String getReference() {
        return reference;
    }

    /**
     * Returns the reference in its configured source form, i.e. {@code {$<reference>}}.
     *
     * @return the decorated reference token.
     */
    @Override
    public String toString() {
        return "{$" + reference + "}";
    }
}
