001: /*_############################################################################
002: _##
003: _## SNMP4J - Session.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;
022:
023: import org.snmp4j.event.*;
024: import java.io.IOException;
025:
026: /**
027: * <code>Session</code> defines a common interface for all classes that
028: * implement SNMP protocol operations based on SNMP4J.
029: *
030: * @author Frank Fock
031: * @version 1.2
032: */
033: public interface Session {
034:
035: /**
036: * Closes the session and frees any allocated resources, i.e. sockets.
037: * After a <code>Session</code> has been closed it must
038: * be used.
039: * @throws IOException
040: * if the session could not free all resources.
041: */
042: public void close() throws IOException;
043:
044: /**
045: * Sends a <code>PDU</code> to the given target and returns the received
046: * response <code>PDU</code>.
047: * @param pdu
048: * the <code>PDU</code> to send.
049: * @param target
050: * the <code>Target</code> instance that specifies how and where to send
051: * the PDU.
052: * @return
053: * the received response encapsulated in a <code>ResponseEvent</code>
054: * instance. To obtain the received response <code>PDU</code> call
055: * {@link ResponseEvent#getResponse()}. If the request timed out,
056: * that method will return <code>null</code>. If the sent <code>pdu</code>
057: * is an unconfirmed PDU (notification, response, or report), then
058: * <code>null</code> will be returned.
059: * @throws IOException
060: * if the message could not be send.
061: */
062: public ResponseEvent send(PDU pdu, Target target)
063: throws IOException;
064:
065: /**
066: * Asynchronously sends a <code>PDU</code> to the given target. The response
067: * is then returned by calling the supplied <code>ResponseListener</code>
068: * instance.
069: *
070: * @param pdu
071: * the PDU instance to send.
072: * @param target
073: * the Target instance representing the target SNMP engine where to send
074: * the <code>pdu</code>.
075: * @param userHandle
076: * an user defined handle that is returned when the request is returned
077: * via the <code>listener</code> object.
078: * @param listener
079: * a <code>ResponseListener</code> instance that is called when
080: * <code>pdu</code> is a confirmed PDU and the request is either answered
081: * or timed out.
082: * @throws IOException
083: * if the message could not be send.
084: */
085: public void send(PDU pdu, Target target, Object userHandle,
086: ResponseListener listener) throws IOException;
087:
088: /**
089: * Sends a <code>PDU</code> to the given target and returns the received
090: * response <code>PDU</code> encapsulated in a <code>ResponseEvent</code>
091: * object that also includes:
092: * <ul>
093: * <li>the transport address of the response sending peer,
094: * <li>the <code>Target</code> information of the target,
095: * <li>the request <code>PDU</code>,
096: * <li>the response <code>PDU</code> (if any).
097: * </ul>
098: * @param pdu
099: * the PDU instance to send.
100: * @param target
101: * the Target instance representing the target SNMP engine where to send
102: * the <code>pdu</code>.
103: * @param transport
104: * specifies the <code>TransportMapping</code> to be used when sending
105: * the PDU. If <code>transport</code> is <code>null</code>, the associated
106: * message dispatcher will try to determine the transport mapping by the
107: * <code>target</code>'s address.
108: * @return
109: * the received response encapsulated in a <code>ResponseEvent</code>
110: * instance. To obtain the received response <code>PDU</code> call
111: * {@link ResponseEvent#getResponse()}. If the request timed out,
112: * that method will return <code>null</code>. If the sent <code>pdu</code>
113: * is an unconfirmed PDU (notification, response, or report), then
114: * <code>null</code> will be returned.
115: * @throws IOException
116: * if the message could not be send.
117: */
118: public ResponseEvent send(PDU pdu, Target target,
119: TransportMapping transport) throws IOException;
120:
121: /**
122: * Asynchronously sends a <code>PDU</code> to the given target. The response
123: * is then returned by calling the supplied <code>ResponseListener</code>
124: * instance.
125: *
126: * @param pdu
127: * the PDU instance to send.
128: * @param target
129: * the Target instance representing the target SNMP engine where to send
130: * the <code>pdu</code>.
131: * @param transport
132: * specifies the <code>TransportMapping</code> to be used when sending
133: * the PDU. If <code>transport</code> is <code>null</code>, the associated
134: * message dispatcher will try to determine the transport mapping by the
135: * <code>target</code>'s address.
136: * @param userHandle
137: * an user defined handle that is returned when the request is returned
138: * via the <code>listener</code> object.
139: * @param listener
140: * a <code>ResponseListener</code> instance that is called when
141: * <code>pdu</code> is a confirmed PDU and the request is either answered
142: * or timed out.
143: * @throws IOException
144: * if the message could not be send.
145: */
146: public void send(PDU pdu, Target target,
147: TransportMapping transport, Object userHandle,
148: ResponseListener listener) throws IOException;
149:
150: /**
151: * Cancels an asynchronous request. Any asynchronous request must be canceled
152: * when the supplied response listener is being called, even if the
153: * <code>ResponseEvent</code> indicates an error.
154: * @param request
155: * a request PDU as sent via {@link #send(PDU pdu, Target target,
156: * Object userHandle, ResponseListener listener)} or any .
157: * @param listener
158: * a ResponseListener instance.
159: */
160: public void cancel(PDU request, ResponseListener listener);
161: }
|