001: /*_############################################################################
002: _##
003: _## SNMP4J-Agent - Request.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.OID;
024: import java.util.Iterator;
025: import java.util.NoSuchElementException;
026: import org.snmp4j.smi.OctetString;
027:
028: /**
029: * The <code>Request</code> interface defines common elements of SNMP related
030: * operation requests.
031: *
032: * @author Frank Fock
033: * @version 1.0
034: */
035: public interface Request {
036:
037: int PHASE_INIT = -1;
038: int PHASE_1PC = 0;
039: int PHASE_2PC_PREPARE = 1;
040: int PHASE_2PC_COMMIT = 2;
041: int PHASE_2PC_UNDO = 3;
042: int PHASE_2PC_CLEANUP = 4;
043:
044: /**
045: * Return the index of the first subrequest with supplied object identifier.
046: * @param oid OID
047: * the <code>OID</code> to search.
048: * @return
049: * a value >= 0 if this request contains a variable binding with the
050: * supplied OID, otherwise -1 is returned.
051: */
052: // int indexOf(OID oid);
053:
054: /**
055: * Return the index of the first subrequest with supplied object identifier.
056: * @param oid OID
057: * the <code>OID</code> to search.
058: * @param startFrom
059: * the zero based index to start search.
060: * @return
061: * a value >= startFrom if this request contains a variable binding with
062: * the supplied OID at index <code>startFrom</code> or greater,
063: * otherwise -1 is returned.
064: */
065: // int indexOf(OID oid, int startFrom);
066: /**
067: * Finds the first sub-request whose OID starts with the supplied one.
068: * @param prefix
069: * the OID prefix of the sub-request OID.
070: * @return
071: * the first <code>SubRequest</code> instance of this request whose OID
072: * starts with <code>prefix</code>. If no such sub-request exits
073: * <code>null</code> is returned.
074: */
075: SubRequest find(OID prefix);
076:
077: /**
078: * Returns the response object for this request.
079: * @return
080: * an object containing the response for this request.
081: */
082: Object getResponse();
083:
084: /**
085: * Checks whether the response for this request is complete.
086: * @return
087: * <code>true</code> if all required data has been collected to create
088: * a response for this request, <code>false</code> otherwise.
089: */
090: boolean isComplete();
091:
092: /**
093: * Checks whether the current phase is complete.
094: * @return
095: * <code>true</code> if all required processing has been finished for
096: * the current request phase. For single phase request types this method
097: * returns the same result as {@link #isComplete()}.
098: */
099: boolean isPhaseComplete();
100:
101: /**
102: * Returns the initiating event object for the request.
103: * @return
104: * an <code>Object</code> instance on whose behalf this request
105: * has been initiated.
106: */
107: Object getSource();
108:
109: /**
110: * Gets the context of the request.
111: * @return
112: * an <code>OctetString</code> instance.
113: */
114: OctetString getContext();
115:
116: /**
117: * Gets the sub-request at the specified index.
118: * @param index
119: * an index <code>>= 0 and < size()</code>
120: * @return
121: * a <code>SnmpSubRequest</code> instance.
122: */
123: SubRequest get(int index);
124:
125: /**
126: * Gets the number of sub-requests in this request. For GETBULK requests
127: * this number may increase over time.
128: * @return
129: * a positive integer (greater or equal to zero).
130: */
131: int size();
132:
133: /**
134: * Gets the phase identifier of the current Two-Phase-Commit (2PC) phase of
135: * this request.
136: * @return
137: * a 2PC identifier
138: */
139: int getPhase();
140:
141: /**
142: * Initializes next phase and returns its identifier.
143: * @return
144: * a phase identifier.
145: * @throws NoSuchElementException if there is no next phase for this type
146: * of request.
147: */
148: int nextPhase() throws NoSuchElementException;
149:
150: /**
151: * Sets the request phase.
152: * @param phase
153: * a phase identifier.
154: * @throws NoSuchElementException if there is no such phase for this type
155: * of request.
156: */
157: void setPhase(int phase) throws NoSuchElementException;
158:
159: /**
160: * Returns an <code>Iterator</code> over the sub-requests of this request.
161: * @return
162: * an <code>Iterator</code>
163: */
164: Iterator iterator();
165:
166: void setViewName(OctetString viewName);
167:
168: OctetString getViewName();
169:
170: OctetString getSecurityName();
171:
172: int getMessageProcessingModel();
173:
174: int getSecurityModel();
175:
176: int getSecurityLevel();
177:
178: int getViewType();
179:
180: void setErrorStatus(int errorStatus);
181:
182: int getErrorStatus();
183:
184: int getErrorIndex();
185:
186: int getTransactionID();
187:
188: /**
189: * Set the processed status of each (incomplete) sub-request to
190: * <code>false</code>.
191: */
192: void resetProcessedStatus();
193:
194: /**
195: * Returns the value of the reprocessing counter associated with this request.
196: * The reprocessing counter can be used to detect and handle endless-loop
197: * errors caused by instrumentation code not setting the completion status
198: * of a sub-request correctly.
199: * @return
200: * 0 after the initial (and normally last) processing iteration and
201: * <code>n</code> after the <code>n</code>-th reprocessing iteration.
202: * @see #incReprocessCounter()
203: */
204: int getReprocessCounter();
205:
206: /**
207: * Increments the reprocess counter by one.
208: * @see #getReprocessCounter()
209: */
210: void incReprocessCounter();
211: }
|