001: /*_############################################################################
002: _##
003: _## SNMP4J - RetrievalEvent.java
004: _##
005: _## Copyright (C) 2003-2008 Frank Fock and Jochen Katz (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.util;
022:
023: import java.util.EventObject;
024: import org.snmp4j.PDU;
025: import org.snmp4j.smi.VariableBinding;
026: import java.util.Arrays;
027:
028: /**
029: * The <code>RetrievalEvent</code> is an abstract class representing the result
030: * of one or more GET/GETNEXT/GETBULK requests.
031: *
032: * @author Frank Fock
033: * @version 1.8
034: * @since 1.8
035: */
036: public abstract class RetrievalEvent extends EventObject {
037:
038: /**
039: * Retrieval operation was successfull.
040: */
041: public static final int STATUS_OK = 0;
042: /**
043: * A request to the agent timed out.
044: */
045: public static final int STATUS_TIMEOUT = -1;
046: /**
047: * The agent failed to return the objects in lexicographic order.
048: */
049: public static final int STATUS_WRONG_ORDER = -2;
050: /**
051: * A report has been received from the agent.
052: * @see #getReportPDU()
053: */
054: public static final int STATUS_REPORT = -3;
055: /**
056: * An exception occured during retrieval operation.
057: * @see #getException()
058: */
059: public static final int STATUS_EXCEPTION = -4;
060:
061: protected VariableBinding[] vbs;
062: protected int status = STATUS_OK;
063: protected Object userObject;
064: protected Exception exception;
065: protected PDU reportPDU;
066:
067: protected RetrievalEvent(Object source, Object userObject) {
068: super (source);
069: this .userObject = userObject;
070: }
071:
072: /**
073: * Creates a retrieval event with a status.
074: * @param source
075: * the source of the event.
076: * @param userObject
077: * the user object or <code>null</code>.
078: * @param status
079: * one of the status constants defined for this object.
080: */
081: public RetrievalEvent(Object source, Object userObject, int status) {
082: this (source, userObject);
083: this .status = status;
084: }
085:
086: /**
087: * Creates a retrieval event with an exception.
088: * @param source
089: * the source of the event.
090: * @param userObject
091: * the user object or <code>null</code>.
092: * @param exception
093: * an exception instance.
094: */
095: public RetrievalEvent(Object source, Object userObject,
096: Exception exception) {
097: this (source, userObject);
098: this .exception = exception;
099: this .status = STATUS_EXCEPTION;
100: }
101:
102: /**
103: * Creates a retrieval event with a report PDU.
104: * @param source
105: * the source of the event.
106: * @param userObject
107: * the user object or <code>null</code>.
108: * @param report
109: * a PDU of type {@link PDU#REPORT}.
110: */
111: public RetrievalEvent(Object source, Object userObject, PDU report) {
112: this (source, userObject);
113: this .reportPDU = report;
114: this .status = STATUS_REPORT;
115: }
116:
117: /**
118: * Creates a retrieval event with row data.
119: *
120: * @param source
121: * the source of the event.
122: * @param userObject
123: * the user object or <code>null</code>.
124: * @param variableBindings
125: * an array of <code>VariableBinding</code> instances.
126: */
127: public RetrievalEvent(Object source, Object userObject,
128: VariableBinding[] variableBindings) {
129: this (source, userObject);
130: this .vbs = variableBindings;
131: }
132:
133: /**
134: * Gets the status of the table operation.
135: * @return
136: * one of the status constants defined for this object.
137: * {@link #STATUS_OK} indicates success, all other values indicate
138: * failure of the operation.
139: */
140: public int getStatus() {
141: return status;
142: }
143:
144: /**
145: * Indicates whether the event reports an error or not.
146: * @return
147: * <code>true</code> if the operation failed with an error.
148: */
149: public boolean isError() {
150: return (status != STATUS_OK);
151: }
152:
153: /**
154: * Gets the user object that has been specified by the user when the retrieval
155: * operation that fired this event has been requested.
156: * @return
157: * an object instance if an user object has been specified or
158: * <code>null</code> otherwise.
159: */
160: public Object getUserObject() {
161: return userObject;
162: }
163:
164: /**
165: * Gets the exception associated with this event.
166: * @return
167: * an Exception instance if there has been an exception instance
168: * associated with this event ({@link #getStatus()} returns
169: * {@link #STATUS_EXCEPTION}), or <code>null</code> otherwise.
170: */
171: public Exception getException() {
172: return exception;
173: }
174:
175: /**
176: * Gets the report PDU associated with this event.
177: * @return
178: * a <code>ScopedPDU</code> instance if there has been a report PDU
179: * instance associated with this event ({@link #getStatus()} returns
180: * {@link #STATUS_REPORT}), or <code>null</code> otherwise.
181: */
182: public PDU getReportPDU() {
183: return reportPDU;
184: }
185:
186: /**
187: * Returns a textual error message for the error.
188: * @return
189: * an error message or an empty string if no error occurred.
190: */
191: public String getErrorMessage() {
192: switch (status) {
193: case STATUS_EXCEPTION: {
194: return exception.getMessage();
195: }
196: case STATUS_REPORT: {
197: return "Report: " + reportPDU.get(0);
198: }
199: case STATUS_TIMEOUT: {
200: return "Request timed out.";
201: }
202: case STATUS_WRONG_ORDER: {
203: return "Agent did not return variable bindings in lexicographic order.";
204: }
205: default: {
206: return "";
207: }
208: }
209: }
210:
211: public String toString() {
212: return getClass().getName() + "[vbs="
213: + ((vbs == null) ? "null" : "" + Arrays.asList(vbs))
214: + ",status=" + status + ",exception=" + exception
215: + ",report=" + reportPDU + "]";
216: }
217:
218: }
|