KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > snmp4j > agent > request > SubRequest


1 /*_############################################################################
2   _##
3   _## SNMP4J-Agent - SubRequest.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.VariableBinding;
25 import org.snmp4j.agent.MOScope;
26 import org.snmp4j.agent.ManagedObject;
27 import org.snmp4j.agent.MOQuery;
28
29 /**
30  * The <code>SubRequest</code> interface defines
31  * @author Frank Fock
32  * @version 1.0.1
33  */
34 public interface SubRequest {
35
36   /**
37    * Indicates whether this (sub-)request has an error.
38    * @return
39    * <code>true</code> if this request (and thus also this sub-request) has
40    * an error status greater than zero.
41    */
42   boolean hasError();
43
44   /**
45    * Sets the error status for this sub-request. Calling this method is a
46    * shortcut for <code>{@link #getStatus()}.setErrorStatus(int errorStatus)
47    * </code>.
48    * @param errorStatus
49    * a SNMPv2/v3 error status.
50    * @since 1.0.1
51    */
52   void setErrorStatus(int errorStatus);
53
54   /**
55    * Gets the error status for this sub-request. Calling this method is a
56    * shortcut for <code>{@link #getStatus()}.getErrorStatus()
57    * </code>.
58    * @return
59    * a SNMPv2/v3 error status.
60    * @since 1.0.1
61    */
62   int getErrorStatus();
63
64   /**
65    * Gets the status object associated with this sub-request.
66    * @return
67    * a RequestStatus instance.
68    */
69   RequestStatus getStatus();
70
71   /**
72    * Gets the scope for this subrequest. The scope is solely defined by this
73    * sub-request and possible request processing that has already excluded
74    * managed objects from the scope of this sub-request.
75    * @return
76    * a <code>MOScope</code> instance.
77    */
78   MOScope getScope();
79
80   /**
81    * Returns the variable binding associated with the sub-request. In order to
82    * process a sub-request this variable binding needs to be modified (if not
83    * an error condition prevents that).
84    * @return
85    * the <code>VariableBinding</code> that holds the sub-request result
86    * or operation parameter (in case of a SET request).
87    */
88   VariableBinding getVariableBinding();
89
90   /**
91    * Gets the request this sub-request belongs to.
92    * @return
93    * a Request instance.
94    */
95   Request getRequest();
96
97   /**
98    * Gets the undo value object associated with this sub-request.
99    * @return
100    * an Object that has previously been associated with this request by
101    * calling {@link #setUndoValue}.
102    */
103   Object JavaDoc getUndoValue();
104
105   /**
106    * Associates an undo value object with this sub-request. The undo
107    * value is internally used by the SNMP4J-Agent API and should therefore
108    * not be altered externally. One exception to this rule is an implementation
109    * of the {@link ManagedObject} interface that does not extend any other
110    * API class.
111    *
112    * @param undoInformation
113    * an object that represents/contains all necessary information to undo
114    * this sub-request.
115    */
116   void setUndoValue(Object JavaDoc undoInformation);
117
118   /**
119    * Marks the sub-request as completed. This is a shortcut for
120    * calling {@link #getStatus()} and then
121    * {@link RequestStatus#setPhaseComplete} to <code>true</code>.
122    */
123   void completed();
124
125   /**
126    * Checks whether the sub-request has been completed and needs no further
127    * processing.
128    * @return
129    * <code>true</code> if the sub-request has been finished and should not
130    * be processed any more.
131    */
132   boolean isComplete();
133
134   /**
135    * Sets the <code>ManagedObject</code> that is determined as the target object
136    * of this sub-request by the agent framework. For SET requests the target
137    * managed object is locked and referenced here to make sure that all locks
138    * are released when a request is answered. In addition, SET requests are
139    * processed in multiple phases and referencing the target managed objects
140    * increases performance.
141    *
142    * @param managedObject
143    * the <code>ManagedObject</code> responsible for processing this sub-
144    * request.
145    */
146   void setTargetMO(ManagedObject managedObject);
147
148   /**
149    * Gets the <code>ManagedObject</code> that is responsible for processing
150    * this sub-request.
151    *
152    * @return
153    * <code>ManagedObject</code> instance.
154    */
155   ManagedObject getTargetMO();
156
157   /**
158    * Returns the index of this subrequest in the request.
159    * @return
160    * the zero based index.
161    */
162   int getIndex();
163
164   /**
165    * Sets the query associated with this subrequest. The query is not used
166    * by the request itself but may be stored here for further reference
167    * while processing this sub-requests.
168    *
169    * @param query
170    * a <code>MOQuery</code> instance representing the query resulting from
171    * this sub-request.
172    */
173   void setQuery(MOQuery query);
174
175   /**
176    * Gets the query previously associated with this sub-request. A sub-request
177    * is associated during requests processing with a instrumentation query.
178    * @return
179    * a <code>MOQuery</code> that describes which manage objects match
180    * this sub-request.
181    */
182   MOQuery getQuery();
183
184   /**
185    * Returns an iterator on the repetitions of this sub-request. On requests
186    * other than GETBULK requests this method returns an empty iterator.
187    * @return
188    * a SubRequestIterator enumerating the repetitions on this sub-requests
189    * starting with this sub-request.
190    */
191   SubRequestIterator repetitions();
192
193   /**
194    * Updates the next repetition's scope and reset any previously set query
195    * to <code>null</code>. The scope of the next repetition is updated
196    * according to the value of this variable binding. If this sub-request
197    * has an error status or exception value, the following repetitions are
198    * set to the same value and exception. Otherwise, the scope of the following
199    * sub-request is the open interval from this sub-request's OID
200    * (not-including) to any OID value.
201    */
202   void updateNextRepetition();
203
204   /**
205    * Gets the user object that has previously associated with this sub-request.
206    *
207    * @return
208    * an object.
209    * @since 1.0.1
210    */
211   Object JavaDoc getUserObject();
212
213   /**
214    * Sets the user object. The user object can be used to associate resources
215    * or any other type of information necessary for a managed object instance
216    * to process a SNMP request. When the request is processed, this reference
217    * will be set to <code>null</code>.
218    *
219    * @param userObject
220    * an object that is not processed or interpreted by the agent API.
221    * @since 1.0.1
222    */
223   void setUserObject(Object JavaDoc userObject);
224 }
225
Popular Tags