View Javadoc

1   //
2   //  ========================================================================
3   //  Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
4   //  ------------------------------------------------------------------------
5   //  All rights reserved. This program and the accompanying materials
6   //  are made available under the terms of the Eclipse Public License v1.0
7   //  and Apache License v2.0 which accompanies this distribution.
8   //
9   //      The Eclipse Public License is available at
10  //      http://www.eclipse.org/legal/epl-v10.html
11  //
12  //      The Apache License v2.0 is available at
13  //      http://www.opensource.org/licenses/apache2.0.php
14  //
15  //  You may elect to redistribute this code under either of these licenses.
16  //  ========================================================================
17  //
18  
19  package org.eclipse.jetty.websocket.common;
20  
21  import java.net.InetSocketAddress;
22  import java.util.concurrent.Executor;
23  
24  import org.eclipse.jetty.io.ByteBufferPool;
25  import org.eclipse.jetty.websocket.api.SuspendToken;
26  import org.eclipse.jetty.websocket.api.WebSocketPolicy;
27  import org.eclipse.jetty.websocket.api.extensions.IncomingFrames;
28  import org.eclipse.jetty.websocket.api.extensions.OutgoingFrames;
29  import org.eclipse.jetty.websocket.common.io.IOState;
30  
31  public interface LogicalConnection extends OutgoingFrames, SuspendToken
32  {
33      /**
34       * Send a websocket Close frame, without a status code or reason.
35       * <p>
36       * Basic usage: results in an non-blocking async write, then connection close.
37       * 
38       * @see org.eclipse.jetty.websocket.api.StatusCode
39       * @see #close(int, String)
40       */
41      public void close();
42  
43      /**
44       * Send a websocket Close frame, with status code.
45       * <p>
46       * Advanced usage: results in an non-blocking async write, then connection close.
47       * 
48       * @param statusCode
49       *            the status code
50       * @param reason
51       *            the (optional) reason. (can be null for no reason)
52       * @see org.eclipse.jetty.websocket.api.StatusCode
53       */
54      public void close(int statusCode, String reason);
55  
56      /**
57       * Terminate the connection (no close frame sent)
58       */
59      void disconnect();
60  
61      /**
62       * Get the ByteBufferPool in use by the connection
63       * @return the buffer pool
64       */
65      ByteBufferPool getBufferPool();
66      
67      /**
68       * Get the Executor used by this connection.
69       * @return the executor
70       */
71      Executor getExecutor();
72  
73      /**
74       * Get the read/write idle timeout.
75       * 
76       * @return the idle timeout in milliseconds
77       */
78      public long getIdleTimeout();
79  
80      /**
81       * Get the IOState of the connection.
82       * 
83       * @return the IOState of the connection.
84       */
85      IOState getIOState();
86  
87      /**
88       * Get the local {@link InetSocketAddress} in use for this connection.
89       * <p>
90       * Note: Non-physical connections, like during the Mux extensions, or during unit testing can result in a InetSocketAddress on port 0 and/or on localhost.
91       * 
92       * @return the local address.
93       */
94      InetSocketAddress getLocalAddress();
95  
96      /**
97       * Set the maximum number of milliseconds of idleness before the connection is closed/disconnected, (ie no frames are either sent or received)
98       * @return the idle timeout in milliseconds
99       */
100     long getMaxIdleTimeout();
101 
102     /**
103      * The policy that the connection is running under.
104      * @return the policy for the connection
105      */
106     WebSocketPolicy getPolicy();
107 
108     /**
109      * Get the remote Address in use for this connection.
110      * <p>
111      * Note: Non-physical connections, like during the Mux extensions, or during unit testing can result in a InetSocketAddress on port 0 and/or on localhost.
112      * 
113      * @return the remote address.
114      */
115     InetSocketAddress getRemoteAddress();
116 
117     /**
118      * Test if logical connection is still open
119      * 
120      *  @return true if connection is open
121      */
122     public boolean isOpen();
123 
124     /**
125      * Tests if the connection is actively reading.
126      * 
127      * @return true if connection is actively attempting to read.
128      */
129     boolean isReading();
130 
131     /**
132      * Set the maximum number of milliseconds of idleness before the connection is closed/disconnected, (ie no frames are either sent or received)
133      * <p>
134      * This idle timeout cannot be garunteed to take immediate effect for any active read/write actions.
135      * New read/write actions will have this new idle timeout.
136      * 
137      * @param ms
138      *            the number of milliseconds of idle timeout
139      */
140     void setMaxIdleTimeout(long ms);
141 
142     /**
143      * Set where the connection should send the incoming frames to.
144      * <p>
145      * Often this is from the Parser to the start of the extension stack, and eventually on to the session.
146      * 
147      * @param incoming
148      *            the incoming frames handler
149      */
150     void setNextIncomingFrames(IncomingFrames incoming);
151 
152     /**
153      * Suspend a the incoming read events on the connection.
154      * @return the suspend token
155      */
156     SuspendToken suspend();
157 
158     /**
159      * Get Unique ID for the Connection
160      * @return the unique ID for the connection
161      */
162     public String getId();
163 }