Request


1   /*_############################################################################
2     _## 
3     _##  SNMP4J-Agent - Request.java  
4     _## 
5     _##  Copyright (C) 2005-2007  Frank Fock (SNMP4J.org)
6     _##  
7     _##  Licensed under the Apache License, Version 2.0 (the "License");
8     _##  you may not use this file except in compliance with the License.
9     _##  You may obtain a copy of the License at
10    _##  
11    _##      http://www.apache.org/licenses/LICENSE-2.0
12    _##  
13    _##  Unless required by applicable law or agreed to in writing, software
14    _##  distributed under the License is distributed on an "AS IS" BASIS,
15    _##  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16    _##  See the License for the specific language governing permissions and
17    _##  limitations under the License.
18    _##  
19    _##########################################################################*/
20  
21  
22  package org.snmp4j.agent.request;
23  
24  import org.snmp4j.smi.OID;
25  import java.util.Iterator  ;
26  import java.util.NoSuchElementException  ;
27  import org.snmp4j.smi.OctetString;
28  
29  /**
30   * The <code>Request</code> interface defines common elements of SNMP related
31   * operation requests.
32   *
33   * @author Frank Fock
34   * @version 1.0
35   */
36  public interface Request {
37  
38    int PHASE_INIT = -1;
39    int PHASE_1PC = 0;
40    int PHASE_2PC_PREPARE  = 1;
41    int PHASE_2PC_COMMIT   = 2;
42    int PHASE_2PC_UNDO     = 3;
43    int PHASE_2PC_CLEANUP  = 4;
44  
45    /**
46     * Return the index of the first subrequest with supplied object identifier.
47     * @param oid OID
48     *    the <code>OID</code> to search.
49     * @return
50     *    a value &gt;= 0 if this request contains a variable binding with the
51     *    supplied OID, otherwise -1 is returned.
52     */
53  //  int indexOf(OID oid);
54  
55  
56    /**
57     * Return the index of the first subrequest with supplied object identifier.
58     * @param oid OID
59     *    the <code>OID</code> to search.
60     * @param startFrom
61     *    the zero based index to start search.
62     * @return
63     *    a value &gt;= startFrom if this request contains a variable binding with
64     *    the supplied OID at index <code>startFrom</code> or greater,
65     *    otherwise -1 is returned.
66     */
67  //  int indexOf(OID oid, int startFrom);
68  
69    /**
70     * Finds the first sub-request whose OID starts with the supplied one.
71     * @param prefix
72     *    the OID prefix of the sub-request OID.
73     * @return
74     *    the first <code>SubRequest</code> instance of this request whose OID
75     *    starts with <code>prefix</code>. If no such sub-request exits
76     *    <code>null</code> is returned.
77     */
78    SubRequest find(OID prefix);
79  
80    /**
81     * Returns the response object for this request.
82     * @return
83     *    an object containing the response for this request.
84     */
85    Object   getResponse();
86  
87    /**
88     * Checks whether the response for this request is complete.
89     * @return
90     *    <code>true</code> if all required data has been collected to create
91     *    a response for this request, <code>false</code> otherwise.
92     */
93    boolean isComplete();
94  
95    /**
96     * Checks whether the current phase is complete.
97     * @return
98     *    <code>true</code> if all required processing has been finished for
99     *    the current request phase. For single phase request types this method
100    *    returns the same result as {@link #isComplete()}.
101    */
102   boolean isPhaseComplete();
103 
104   /**
105    * Returns the initiating event object for the request.
106    * @return
107    *    an <code>Object</code> instance on whose behalf this request
108    *    has been initiated.
109    */
110   Object   getSource();
111 
112   /**
113    * Gets the context of the request.
114    * @return
115    *    an <code>OctetString</code> instance.
116    */
117   OctetString getContext();
118 
119   /**
120    * Gets the sub-request at the specified index.
121    * @param index
122    *    an index <code>&gt;= 0 and &lt; size()</code>
123    * @return
124    *    a <code>SnmpSubRequest</code> instance.
125    */
126   SubRequest get(int index);
127 
128   /**
129    * Gets the number of sub-requests in this request. For GETBULK requests
130    * this number may increase over time.
131    * @return
132    *    a positive integer (greater or equal to zero).
133    */
134   int size();
135 
136   /**
137    * Gets the phase identifier of the current Two-Phase-Commit (2PC) phase of
138    * this request.
139    * @return
140    *    a 2PC identifier
141    */
142   int getPhase();
143 
144   /**
145    * Initializes next phase and returns its identifier.
146    * @return
147    *    a phase identifier.
148    * @throws NoSuchElementException if there is no next phase for this type
149    * of request.
150    */
151   int nextPhase() throws NoSuchElementException  ;
152 
153   /**
154    * Sets the request phase.
155    * @param phase
156    *    a phase identifier.
157    * @throws NoSuchElementException if there is no such phase for this type
158    * of request.
159    */
160   void setPhase(int phase) throws NoSuchElementException  ;
161 
162   /**
163    * Returns an <code>Iterator</code> over the sub-requests of this request.
164    * @return
165    *    an <code>Iterator</code>
166    */
167   Iterator   iterator();
168 
169   void setViewName(OctetString viewName);
170 
171   OctetString getViewName();
172 
173   OctetString getSecurityName();
174 
175   int getMessageProcessingModel();
176 
177   int getSecurityModel();
178 
179   int getSecurityLevel();
180 
181   int getViewType();
182 
183   void setErrorStatus(int errorStatus);
184 
185   int getErrorStatus();
186 
187   int getErrorIndex();
188 
189   int getTransactionID();
190 
191   /**
192    * Set the processed status of each (incomplete) sub-request to
193    * <code>false</code>.
194    */
195   void resetProcessedStatus();
196 
197   /**
198    * Returns the value of the reprocessing counter associated with this request.
199    * The reprocessing counter can be used to detect and handle endless-loop
200    * errors caused by instrumentation code not setting the completion status
201    * of a sub-request correctly.
202    * @return
203    *    0 after the initial (and normally last) processing iteration and
204    *    <code>n</code> after the <code>n</code>-th reprocessing iteration.
205    * @see #incReprocessCounter()
206    */
207   int getReprocessCounter();
208 
209   /**
210    * Increments the reprocess counter by one.
211    * @see #getReprocessCounter()
212    */
213   void incReprocessCounter();
214 }
215
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags