org.snmp4j.agent.request.Request Maven / Gradle / Ivy

Go to download
/*_############################################################################
  _## 
  _##  SNMP4J-Agent - Request.java  
  _## 
  _##  Copyright (C) 2005-2009  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.request;

import org.snmp4j.smi.OID;
import java.util.Iterator;
import java.util.NoSuchElementException;
import org.snmp4j.smi.OctetString;
// JavaDoc
import org.snmp4j.agent.ManagedObject;

/**
 * The Request interface defines common elements of SNMP related
 * operation requests.
 *
 * @author Frank Fock
 * @version 1.2
 */
public interface Request {

  int PHASE_INIT = -1;
  int PHASE_1PC = 0;
  int PHASE_2PC_PREPARE  = 1;
  int PHASE_2PC_COMMIT   = 2;
  int PHASE_2PC_UNDO     = 3;
  int PHASE_2PC_CLEANUP  = 4;

  /**
   * Finds the first sub-request whose OID starts with the supplied one.
   * @param prefix
   *    the OID prefix of the sub-request OID.
   * @return
   *    the first SubRequest instance of this request whose OID
   *    starts with prefix. If no such sub-request exits
   *    null is returned.
   */
  SubRequest find(OID prefix);

  /**
   * Returns the response object for this request.
   * @return
   *    an object containing the response for this request.
   */
  Object getResponse();

  /**
   * Checks whether the response for this request is complete.
   * @return
   *    true if all required data has been collected to create
   *    a response for this request, false otherwise.
   */
  boolean isComplete();

  /**
   * Checks whether the current phase is complete.
   * @return
   *    true if all required processing has been finished for
   *    the current request phase. For single phase request types this method
   *    returns the same result as {@link #isComplete()}.
   */
  boolean isPhaseComplete();

  /**
   * Returns the initiating event object for the request.
   * @return
   *    an Object instance on whose behalf this request
   *    has been initiated.
   */
  Object getSource();

  /**
   * Gets the context of the request.
   * @return
   *    an OctetString instance.
   */
  OctetString getContext();

  /**
   * Gets the sub-request at the specified index.
   * @param index
   *    an index >= 0 and < size()
   * @return
   *    a SnmpSubRequest instance.
   */
  SubRequest get(int index);

  /**
   * Gets the number of sub-requests in this request. For GETBULK requests
   * this number may increase over time.
   * @return
   *    a positive integer (greater or equal to zero).
   */
  int size();

  /**
   * Gets the phase identifier of the current Two-Phase-Commit (2PC) phase of
   * this request.
   * @return
   *    a 2PC identifier
   */
  int getPhase();

  /**
   * Initializes next phase and returns its identifier.
   * @return
   *    a phase identifier.
   * @throws NoSuchElementException if there is no next phase for this type
   * of request.
   */
  int nextPhase() throws NoSuchElementException;

  /**
   * Sets the request phase.
   * @param phase
   *    a phase identifier.
   * @throws NoSuchElementException if there is no such phase for this type
   * of request.
   */
  void setPhase(int phase) throws NoSuchElementException;

  /**
   * Returns an Iterator over the sub-requests of this request.
   * @return
   *    an Iterator
   */
  Iterator iterator();

  void setViewName(OctetString viewName);

  OctetString getViewName();

  OctetString getSecurityName();

  int getMessageProcessingModel();

  int getSecurityModel();

  int getSecurityLevel();

  int getViewType();

  void setErrorStatus(int errorStatus);

  int getErrorStatus();

  int getErrorIndex();

  int getTransactionID();

  /**
   * Set the processed status of each (incomplete) sub-request to
   * false.
   */
  void resetProcessedStatus();

  /**
   * Returns the value of the reprocessing counter associated with this request.
   * The reprocessing counter can be used to detect and handle endless-loop
   * errors caused by instrumentation code not setting the completion status
   * of a sub-request correctly.
   * @return
   *    0 after the initial (and normally last) processing iteration and
   *    n after the n-th reprocessing iteration.
   * @see #incReprocessCounter()
   */
  int getReprocessCounter();

  /**
   * Increments the reprocess counter by one.
   * @see #getReprocessCounter()
   */
  void incReprocessCounter();

  /**
   * Gets the processing user object for the specified key. By default
   * there is no such object associated with a request, but
   * {@link ManagedObject}s may put their own objects into the request
   * (for example to avoid unnecessary updates on behalf of the same request).
   *
   * @param key
   *    an Object.
   * @return
   *    the associated Object or null if their exists no such
   *    association.
   * @since 1.2
   */
  Object getProcessingUserObject(Object key);

  /**
   * Sets an user object association.
   *
   * @param key
   *    a key Object.
   * @param value
   *    a value Object associated with key.
   * @return
   *    the previous value associated with key or null
   *    if no such association existed.
   * @since 1.2
   */
  Object setProcessingUserObject(Object key, Object value);
}