/*_############################################################################
  _## 
  _##  SNMP4J-Agent 3 - MOInput.java  
  _## 
  _##  Copyright (C) 2005-2025  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;

import org.snmp4j.smi.Variable;
import java.io.IOException;

/**
 * The {@code MOInput} models the interface for reading ManagedObject
 * data into a SNMP4J-Agent in a generic way.
 *
 * @author Frank Fock
 * @version 1.2
 */
public interface MOInput {

    /**
     * Returns the update mode, which might be one of the constants defined
     * by {@link ImportMode}.
     * @return
     *    the constant denoting the update mode that should be used by a
     *    {@code SerializableManagedObject} to import its content from
     *    persistent storage.
     */
    int getImportMode();

    /**
     * Reads and returns a {@code Context} from the input source.
     *
     * @return a {@code Context} instance representing the context information
     *         extracted from the input source.
     * @throws IOException if an error occurs while reading the {@code Context}.
     */
    Context readContext() throws IOException;

    /**
     * Skips the specified {@code Context} during the reading process.
     * This method is used to bypass a context in the input stream without processing it.
     *
     * @param context
     *    the {@code Context} instance to be skipped. This represents specific
     *    context information that is available in the input.
     * @throws IOException
     *    if an I/O error occurs while attempting to skip the context in the input stream.
     */
    void skipContext(Context context) throws IOException;

    /**
     * Reads and returns a {@code MOInfo} object from the input source.
     * A {@code MOInfo} instance encapsulates information about a managed object,
     * including its unique identifier (OID) and version details.
     *
     * @return a {@code MOInfo} instance representing the managed object
     *         information read from the input source.
     * @throws IOException if an I/O error occurs while reading the managed object.
     */
    MOInfo readManagedObject() throws IOException;

    /**
     * Skips to the end of the specified managed object's configuration.
     * @param mo
     *    a MOInfo instance.
     * @throws IOException
     *    if the input stream cannot be read.
     */
    void skipManagedObject(MOInfo mo) throws IOException;

    /**
     * Reads a {@code Variable} from the input source.
     *
     * @return a {@code Variable} object representing the data read from the input source.
     * @throws IOException if an I/O error occurs while reading the {@code Variable}.
     */
    Variable readVariable() throws IOException;

    /**
     * Reads and returns a {@code Sequence} from the input source.
     *
     * @return a {@code Sequence} object representing the data read from the input source.
     * @throws IOException if an I/O error occurs while reading the {@code Sequence}.
     */
    Sequence readSequence() throws IOException;

    /**
     * Reads and returns an {@code IndexedVariables} instance from the input source.
     * An {@code IndexedVariables} object encapsulates an index and an array of variables,
     * providing a structured representation of indexed row data.
     *
     * @return an {@code IndexedVariables} instance representing the indexed row data
     *         read from the input.
     * @throws IOException if an I/O error occurs while reading the input source.
     */
    IndexedVariables readIndexedVariables() throws IOException;

    void close() throws IOException;

}
