Session


1   /*_############################################################################
2     _## 
3     _##  SNMP4J - Session.java  
4     _## 
5     _##  Copyright 2003-2007  Frank Fock and Jochen Katz (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  
23  
24  
25  package org.snmp4j;
26  
27  import org.snmp4j.event.*;
28  import java.io.IOException  ;
29  
30  /**
31   * <code>Session</code> defines a common interface for all classes that
32   * implement SNMP protocol operations based on SNMP4J.
33   *
34   * @author Frank Fock
35   * @version 1.1
36   */
37  public interface Session {
38  
39    /**
40     * Closes the session and frees any allocated resources, i.e. sockets.
41     * After a <code>Session</code> has been closed it must
42     * be used.
43     * @throws IOException
44     *    if the session could not free all resources.
45     */
46    public void close() throws IOException  ;
47  
48    /**
49     * Sends a <code>PDU</code> to the given target and returns the received
50     * response <code>PDU</code>.
51     * @param pdu
52     *    the <code>PDU</code> to send.
53     * @param target
54     *    the <code>Target</code> instance that specifies how and where to send
55     *    the PDU.
56     * @return
57     *    the received response encapsulated in a <code>ResponseEvent</code>
58     *    instance. To obtain the received response <code>PDU</code> call
59     *    {@link ResponseEvent#getResponse()}. If the request timed out,
60     *    that method will return <code>null</code>. If the sent <code>pdu</code>
61     *    is an unconfirmed PDU (notification, response, or report), then
62     *    <code>null</code> will be returned.
63     * @throws IOException
64     *    if the message could not be send.
65     */
66    public ResponseEvent send(PDU pdu, Target target) throws IOException  ;
67  
68    /**
69     * Asynchronously sends a <code>PDU</code> to the given target. The response
70     * is then returned by calling the supplied <code>ResponseListener</code>
71     * instance.
72     *
73     * @param pdu
74     *    the PDU instance to send.
75     * @param target
76     *    the Target instance representing the target SNMP engine where to send
77     *    the <code>pdu</code>.
78     * @param userHandle
79     *    an user defined handle that is returned when the request is returned
80     *    via the <code>listener</code> object.
81     * @param listener
82     *    a <code>ResponseListener</code> instance that is called when
83     *    <code>pdu</code> is a confirmed PDU and the request is either answered
84     *    or timed out.
85     * @throws IOException
86     *    if the message could not be send.
87     */
88    public void send(PDU pdu, Target target, Object   userHandle,
89                     ResponseListener listener) throws IOException  ;
90  
91    /**
92     * Sends a <code>PDU</code> to the given target and returns the received
93     * response <code>PDU</code> encapsulated in a <code>ResponseEvent</code>
94     * object that also includes:
95     * <ul>
96     * <li>the transport address of the response sending peer,
97     * <li>the <code>Target</code> information of the target,
98     * <li>the request <code>PDU</code>,
99     * <li>the response <code>PDU</code> (if any).
100    * </ul>
101    * @param pdu
102    *    the PDU instance to send.
103    * @param target
104    *    the Target instance representing the target SNMP engine where to send
105    *    the <code>pdu</code>.
106    * @param transport
107    *    specifies the <code>TransportMapping</code> to be used when sending
108    *    the PDU. If <code>transport</code> is <code>null</code>, the associated
109    *    message dispatcher will try to determine the transport mapping by the
110    *    <code>target</code>'s address.
111    * @return
112    *    the received response encapsulated in a <code>ResponseEvent</code>
113    *    instance. To obtain the received response <code>PDU</code> call
114    *    {@link ResponseEvent#getResponse()}. If the request timed out,
115    *    that method will return <code>null</code>. If the sent <code>pdu</code>
116    *    is an unconfirmed PDU (notification, response, or report), then
117    *    <code>null</code> will be returned.
118    * @throws IOException
119    *    if the message could not be send.
120    */
121   public ResponseEvent send(PDU pdu, Target target,
122                             TransportMapping transport) throws IOException  ;
123 
124   /**
125    * Asynchronously sends a <code>PDU</code> to the given target. The response
126    * is then returned by calling the supplied <code>ResponseListener</code>
127    * instance.
128    *
129    * @param pdu
130    *    the PDU instance to send.
131    * @param target
132    *    the Target instance representing the target SNMP engine where to send
133    *    the <code>pdu</code>.
134    * @param transport
135    *    specifies the <code>TransportMapping</code> to be used when sending
136    *    the PDU. If <code>transport</code> is <code>null</code>, the associated
137    *    message dispatcher will try to determine the transport mapping by the
138    *    <code>target</code>'s address.
139    * @param userHandle
140    *    an user defined handle that is returned when the request is returned
141    *    via the <code>listener</code> object.
142    * @param listener
143    *    a <code>ResponseListener</code> instance that is called when
144    *    <code>pdu</code> is a confirmed PDU and the request is either answered
145    *    or timed out.
146    * @throws IOException
147    *    if the message could not be send.
148    */
149   public void send(PDU pdu, Target target, TransportMapping transport,
150                    Object   userHandle,
151                    ResponseListener listener) throws IOException  ;
152 
153 
154   /**
155    * Cancels an asynchronous request. Any asynchronous request must be canceled
156    * when the supplied response listener is being called, even if the
157    * <code>ResponseEvent</code> indicates an error.
158    * @param request
159    *    a request PDU as sent via {@link #send(PDU pdu, Target target,
160    *    Object userHandle, ResponseListener listener)} or any .
161    * @param listener
162    *    a ResponseListener instance.
163    */
164   public void cancel(PDU request, ResponseListener listener);
165 
166 }
167 
168
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags