001: /*_############################################################################
002: _##
003: _## SNMP4J-Agent - SubRequest.java
004: _##
005: _## Copyright (C) 2005-2007 Frank Fock (SNMP4J.org)
006: _##
007: _## Licensed under the Apache License, Version 2.0 (the "License");
008: _## you may not use this file except in compliance with the License.
009: _## You may obtain a copy of the License at
010: _##
011: _## http://www.apache.org/licenses/LICENSE-2.0
012: _##
013: _## Unless required by applicable law or agreed to in writing, software
014: _## distributed under the License is distributed on an "AS IS" BASIS,
015: _## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016: _## See the License for the specific language governing permissions and
017: _## limitations under the License.
018: _##
019: _##########################################################################*/
020:
021: package org.snmp4j.agent.request;
022:
023: import org.snmp4j.smi.VariableBinding;
024: import org.snmp4j.agent.MOScope;
025: import org.snmp4j.agent.ManagedObject;
026: import org.snmp4j.agent.MOQuery;
027:
028: /**
029: * The <code>SubRequest</code> interface defines
030: * @author Frank Fock
031: * @version 1.0.1
032: */
033: public interface SubRequest {
034:
035: /**
036: * Indicates whether this (sub-)request has an error.
037: * @return
038: * <code>true</code> if this request (and thus also this sub-request) has
039: * an error status greater than zero.
040: */
041: boolean hasError();
042:
043: /**
044: * Sets the error status for this sub-request. Calling this method is a
045: * shortcut for <code>{@link #getStatus()}.setErrorStatus(int errorStatus)
046: * </code>.
047: * @param errorStatus
048: * a SNMPv2/v3 error status.
049: * @since 1.0.1
050: */
051: void setErrorStatus(int errorStatus);
052:
053: /**
054: * Gets the error status for this sub-request. Calling this method is a
055: * shortcut for <code>{@link #getStatus()}.getErrorStatus()
056: * </code>.
057: * @return
058: * a SNMPv2/v3 error status.
059: * @since 1.0.1
060: */
061: int getErrorStatus();
062:
063: /**
064: * Gets the status object associated with this sub-request.
065: * @return
066: * a RequestStatus instance.
067: */
068: RequestStatus getStatus();
069:
070: /**
071: * Gets the scope for this subrequest. The scope is solely defined by this
072: * sub-request and possible request processing that has already excluded
073: * managed objects from the scope of this sub-request.
074: * @return
075: * a <code>MOScope</code> instance.
076: */
077: MOScope getScope();
078:
079: /**
080: * Returns the variable binding associated with the sub-request. In order to
081: * process a sub-request this variable binding needs to be modified (if not
082: * an error condition prevents that).
083: * @return
084: * the <code>VariableBinding</code> that holds the sub-request result
085: * or operation parameter (in case of a SET request).
086: */
087: VariableBinding getVariableBinding();
088:
089: /**
090: * Gets the request this sub-request belongs to.
091: * @return
092: * a Request instance.
093: */
094: Request getRequest();
095:
096: /**
097: * Gets the undo value object associated with this sub-request.
098: * @return
099: * an Object that has previously been associated with this request by
100: * calling {@link #setUndoValue}.
101: */
102: Object getUndoValue();
103:
104: /**
105: * Associates an undo value object with this sub-request. The undo
106: * value is internally used by the SNMP4J-Agent API and should therefore
107: * not be altered externally. One exception to this rule is an implementation
108: * of the {@link ManagedObject} interface that does not extend any other
109: * API class.
110: *
111: * @param undoInformation
112: * an object that represents/contains all necessary information to undo
113: * this sub-request.
114: */
115: void setUndoValue(Object undoInformation);
116:
117: /**
118: * Marks the sub-request as completed. This is a shortcut for
119: * calling {@link #getStatus()} and then
120: * {@link RequestStatus#setPhaseComplete} to <code>true</code>.
121: */
122: void completed();
123:
124: /**
125: * Checks whether the sub-request has been completed and needs no further
126: * processing.
127: * @return
128: * <code>true</code> if the sub-request has been finished and should not
129: * be processed any more.
130: */
131: boolean isComplete();
132:
133: /**
134: * Sets the <code>ManagedObject</code> that is determined as the target object
135: * of this sub-request by the agent framework. For SET requests the target
136: * managed object is locked and referenced here to make sure that all locks
137: * are released when a request is answered. In addition, SET requests are
138: * processed in multiple phases and referencing the target managed objects
139: * increases performance.
140: *
141: * @param managedObject
142: * the <code>ManagedObject</code> responsible for processing this sub-
143: * request.
144: */
145: void setTargetMO(ManagedObject managedObject);
146:
147: /**
148: * Gets the <code>ManagedObject</code> that is responsible for processing
149: * this sub-request.
150: *
151: * @return
152: * <code>ManagedObject</code> instance.
153: */
154: ManagedObject getTargetMO();
155:
156: /**
157: * Returns the index of this subrequest in the request.
158: * @return
159: * the zero based index.
160: */
161: int getIndex();
162:
163: /**
164: * Sets the query associated with this subrequest. The query is not used
165: * by the request itself but may be stored here for further reference
166: * while processing this sub-requests.
167: *
168: * @param query
169: * a <code>MOQuery</code> instance representing the query resulting from
170: * this sub-request.
171: */
172: void setQuery(MOQuery query);
173:
174: /**
175: * Gets the query previously associated with this sub-request. A sub-request
176: * is associated during requests processing with a instrumentation query.
177: * @return
178: * a <code>MOQuery</code> that describes which manage objects match
179: * this sub-request.
180: */
181: MOQuery getQuery();
182:
183: /**
184: * Returns an iterator on the repetitions of this sub-request. On requests
185: * other than GETBULK requests this method returns an empty iterator.
186: * @return
187: * a SubRequestIterator enumerating the repetitions on this sub-requests
188: * starting with this sub-request.
189: */
190: SubRequestIterator repetitions();
191:
192: /**
193: * Updates the next repetition's scope and reset any previously set query
194: * to <code>null</code>. The scope of the next repetition is updated
195: * according to the value of this variable binding. If this sub-request
196: * has an error status or exception value, the following repetitions are
197: * set to the same value and exception. Otherwise, the scope of the following
198: * sub-request is the open interval from this sub-request's OID
199: * (not-including) to any OID value.
200: */
201: void updateNextRepetition();
202:
203: /**
204: * Gets the user object that has previously associated with this sub-request.
205: *
206: * @return
207: * an object.
208: * @since 1.0.1
209: */
210: Object getUserObject();
211:
212: /**
213: * Sets the user object. The user object can be used to associate resources
214: * or any other type of information necessary for a managed object instance
215: * to process a SNMP request. When the request is processed, this reference
216: * will be set to <code>null</code>.
217: *
218: * @param userObject
219: * an object that is not processed or interpreted by the agent API.
220: * @since 1.0.1
221: */
222: void setUserObject(Object userObject);
223: }
|