View Javadoc

1   /* (c) Copyright 2003 Caleigo AB, All rights reserved. 
2    * 
3    * This library is free software; you can redistribute it and/or
4    * modify it under the terms of the GNU Lesser General Public
5    * License as published by the Free Software Foundation; either
6    * version 2.1 of the License, or (at your option) any later version.
7    * 
8    * This library is distributed in the hope that it will be useful,
9    * but WITHOUT ANY WARRANTY; without even the implied warranty of
10   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
11   * Lesser General Public License for more details.
12   * 
13   * You should have received a copy of the GNU Lesser General Public
14   * License along with this library; if not, write to the Free Software
15   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16   *  
17   */
18  
19  package org.caleigo.toolkit.tunnel;
20  
21  /*** <p>An ITunnel is responsible for sending messages between clients and a server.
22   * It hides the underlying protocol that is used for the communication and presents
23   * a clean interface for sending and receiving messages. It also handles the
24   * transformation of messages into sendable data and makes it possible to add any
25   * number of transformation of the data before it is sent.
26   *
27   * <p>Incoming messages are handled by IMessageConsumers. The ITunnel maintains a
28   * list of IMessageConsumers. When a message is received they are asked in order
29   * if they accept the message. The first IMessgeConsumer that accepts the message
30   * becomes the conumer for that message.
31   *
32   * <p>The ITunnel also maintains a list of ITunnelPackers. These packers a responsible
33   * for packing messages that are sent and unpacking messages that are received.
34   *
35   * @author  Dennis Zikovic
36   * @version 1.00
37   * 
38   *//* 
39   *
40   * WHEN        WHO               WHY & WHAT
41   * -----------------------------------------------------------------------------
42   * 2002-02-12  Dennis Zikovic    Creation
43   * 2002-07-01  Mattias Hagstrand Redesign
44   */
45  public interface ITunnel
46  {
47      // Constants ---------------------------------------------------------------
48      
49      // Methods -----------------------------------------------------------------
50      
51      /***
52       * Initializes the ITunnel. This method must be called before any messages
53       * can be sent. After this method has been called it is not possible to
54       * set the ITunnelCodec or to add or remove ITunnelPackers.
55       */
56      public void initialize() throws IllegalStateException, TunnelException;
57      
58      /***
59       * Performs cleanup for this ITunnel. No messages can be sent after this
60       * method has been called. This method will send all messages in the message
61       * queue before closing down.
62       */
63      public void finalize() throws IllegalStateException, TunnelException;
64      
65      /*** Returns <code>true</code> if this tunnel is active, that is, if it is
66       * correctly initialized. If this method returns <code>true</code> then
67       * a call to finalize must not throw an IllegalStateException.
68       */
69      public boolean isActive();
70      
71      /***
72       * Sends a ping message over this ITunnel. This method is typically used to
73       * check that the communication is working.
74       *
75       * @return  the ping time in milli seconds.
76       */
77      public int ping() throws TunnelException;
78      
79      /***
80       * Sends a message over this ITunnel. This method returns after the message
81       * has been sent.
82       */
83      public void send(Object message) throws TunnelException;
84      
85      /***
86       * Sends a request/reply message over this ITunnel. This method blocks until
87       * the reply is received.
88       */
89      public Object ask(Object message) throws TunnelException;
90  
91      /***
92       * Adds the consumer to the end of this ITunnels message consumer list.
93       */
94      public void addMessageConsumer(IMessageConsumer consumer);
95      
96      /***
97       * Removes the consumer from this ITunnels message consumer list.
98       */
99      public void remomveMessageConsumer(IMessageConsumer consumer);
100     
101     /***
102      * Sets the ITunnelCodec that should be used by this ITunnel.
103      */
104     public void setCodec(ITunnelCodec codec) throws IllegalStateException;
105     
106     /***
107      * Adds the packer to the end of this ITunnels packer list.
108      */
109     public void addPacker(ITunnelPacker packer) throws IllegalStateException;
110     
111     /***
112      * Removes the packer from this ITunnels packer list.
113      */
114     public void remomvePacker(ITunnelPacker packer) throws IllegalStateException;
115     
116     /***
117      * Adds the callback to the list of IStatusCallbacks that receives status
118      * messages from this ITunnel.
119      */
120     public void addStatusCallback(IStatusCallback callback);
121     
122     /***
123      * Removes the callback from the list of IStatusCallbacks.
124      */
125     public void removeStatusCallback(IStatusCallback callback);
126     
127     /***
128      * Sets the log level for this ITunnel.
129      */
130     public void setLogLevel(int level);
131     
132     /***
133      * Gets the log level for this ITunnel.
134      */
135     public int getLogLevel();
136     
137     public void addTunnelListener(ITunnelListener listener);
138     
139     public void removeTunnelListener(ITunnelListener listener);
140     
141     /*** Returns a humanly readably text that describes the ITunnel.
142      */
143     public String getDescription();
144     
145     // Nested classes ----------------------------------------------------------
146 }