You are viewing a plain text version of this content. The canonical link for it is here.
Posted to scm@geronimo.apache.org by ga...@apache.org on 2013/06/12 06:13:30 UTC
svn commit: r1492048 [2/3] - in /geronimo/specs/trunk: ./
geronimo-websockets_1.0_spec/ geronimo-websockets_1.0_spec/src/
geronimo-websockets_1.0_spec/src/main/
geronimo-websockets_1.0_spec/src/main/java/
geronimo-websockets_1.0_spec/src/main/java/java...
Added: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnClose.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnClose.java?rev=1492048&view=auto
==============================================================================
--- geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnClose.java (added)
+++ geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnClose.java Wed Jun 12 04:13:29 2013
@@ -0,0 +1,44 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package javax.websocket;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This method level annotation can be used to decorate a Java method that wishes to be called when a web socket session
+ * is closing.
+ * <p/>
+ * The method may only take the following parameters:-
+ * <ul>
+ * <li>optional Session parameter</li>
+ * <li>optional CloseReason parameter</li>
+ * <li>Zero to n String parameters annotated with the PathParam annotation.</li>
+ * </ul>
+ * <p/>
+ * The parameters may appear in any order. See Endpoint.onClose(javax.websocket.Session, javax.websocket.CloseReason)
+ * for more details on how the session parameter may be used during method calls annotated with this annotation.
+ */
+@Retention(value = RetentionPolicy.RUNTIME)
+@Target(value = ElementType.METHOD)
+public @interface OnClose {
+}
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnClose.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnClose.java
------------------------------------------------------------------------------
svn:keywords = Date Revision
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnClose.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnError.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnError.java?rev=1492048&view=auto
==============================================================================
--- geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnError.java (added)
+++ geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnError.java Wed Jun 12 04:13:29 2013
@@ -0,0 +1,44 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package javax.websocket;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This method level annotation can be used to decorate a Java method that wishes to be called in order to handle
+ * errors. See Endpoint.onError(javax.websocket.Session, java.lang.Throwable) for a description of the different
+ * categories of error.
+ * <p/>
+ * The method may only take the following parameters:-
+ * <ul>
+ * <li>optional Session parameter</li>
+ * <li>a Throwable parameter</li>
+ * <li>Zero to n String parameters annotated with the PathParam annotation</li>
+ * </ul>
+ * <p/>
+ * The parameters may appear in any order.
+ */
+@Retention(value = RetentionPolicy.RUNTIME)
+@Target(value = ElementType.METHOD)
+public @interface OnError {
+}
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnError.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnError.java
------------------------------------------------------------------------------
svn:keywords = Date Revision
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnError.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnMessage.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnMessage.java?rev=1492048&view=auto
==============================================================================
--- geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnMessage.java (added)
+++ geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnMessage.java Wed Jun 12 04:13:29 2013
@@ -0,0 +1,100 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package javax.websocket;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This method level annotation can be used to make a Java method receive incoming web socket messages. Each websocket
+ * endpoint may only have one message handling method for each of the native websocket message formats: text, binary and
+ * pong. Methods using this annotation are allowed to have parameters of types described below, otherwise the container
+ * will generate an error at deployment time.
+ * <p/>
+ * The allowed parameters are:
+ * <ol>
+ * <li>Exactly one of any of the following choices
+ * <ul>
+ * <li>if the method is handling text messages:
+ * <ul>
+ * <li>String to receive the whole message</li>
+ * <li>Java primitive or class equivalent to receive the whole message converted to that type</li>
+ * <li>String and boolean pair to receive the message in parts</li>
+ * <li>Reader to receive the whole message as a blocking stream</li>
+ * <li>any object parameter for which the endpoint has a text decoder (Decoder.Text or Decoder.TextStream).</li>
+ * </ul>
+ * </li>
+ * <li>if the method is handling binary messages:
+ * <ul>
+ * <li>byte[] or ByteBuffer to receive the whole message</li>
+ * <li>byte[] and boolean pair, or ByteBuffer and boolean pair to receive the message in parts</li>
+ * <li>InputStream to receive the whole message as a blocking stream</li>
+ * <li>any object parameter for which the endpoint has a binary decoder (Decoder.Binary or Decoder.BinaryStream).</li>
+ * </ul>
+ * </li>
+ * <li>if the method is handling pong messages:
+ * <ul>
+ * <li>PongMessage for handling pong messages</li>
+ * </ul>
+ * </li>
+ * </ul>
+ * </li>
+ * <li>and Zero to n String or Java primitive parameters annotated with the PathParam annotation for server endpoints.</li>
+ * <li>and an optional Session parameter</li>
+ * </ol>
+ * <p/>
+ * The parameters may be listed in any order.
+ * <p/>
+ * The method may have a non-void return type, in which case the web socket runtime must interpret this as a web socket
+ * message to return to the peer. The allowed data types for this return type, other than void, are String, ByteBuffer,
+ * byte[], any Java primitive or class equivalent, and anything for which there is an encoder. If the method uses a Java
+ * primitive as a return value, the implementation must construct the text message to send using the standard Java
+ * string representation of the Java primitive unless there developer provided encoder for the type configured for this
+ * endpoint, in which case that encoder must be used. If the method uses a class equivalent of a Java primitive as a
+ * return value, the implementation must construct the text message from the Java primitive equivalent as described
+ * above.
+ * <p/>
+ * Developers should note that if developer closes the session during the invocation of a method with a return type, the
+ * method will complete but the return value will not be delivered to the remote endpoint. The send failure will be
+ * passed back into the endpoint's error handling method.
+ * <p/>
+ * For example:
+ * <p/>
+ * <code>
+ *
+ * @OnMessage public void processGreeting(String message, Session session) { System.out.println("Greeting received:" +
+ * message); } </code>
+ * <p/>
+ * For example:
+ * <p/>
+ * <code>
+ * @OnMessage public void processUpload(byte[] b, boolean last, Session session) {
+ * // process partial data here, which check on last to see if these is more on the way } </code>
+ * <p/>
+ * Developers should not continue to reference message objects of type Reader, ByteBuffer or InputStream
+ * after the annotated method has completed, since they may be recycled by the implementation.
+ */
+@Retention(value = RetentionPolicy.RUNTIME)
+@Target(value = ElementType.METHOD)
+public @interface OnMessage {
+ long maxMessageSize() default -1L;
+}
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnMessage.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnMessage.java
------------------------------------------------------------------------------
svn:keywords = Date Revision
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnMessage.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnOpen.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnOpen.java?rev=1492048&view=auto
==============================================================================
--- geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnOpen.java (added)
+++ geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnOpen.java Wed Jun 12 04:13:29 2013
@@ -0,0 +1,43 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package javax.websocket;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This method level annotation can be used to decorate a Java method that wishes to be called when a new web socket
+ * session is open.
+ * <p/>
+ * The method may only take the following parameters:-
+ * <ul>
+ * <li>optional Session parameter</li>
+ * <li>optional EndpointConfig parameter</li>
+ * <li>Zero to n String parameters annotated with the PathParam annotation.</li>
+ * </ul>
+ * <p/>
+ * The parameters may appear in any order.
+ */
+@Retention(value = RetentionPolicy.RUNTIME)
+@Target(value = ElementType.METHOD)
+public @interface OnOpen {
+}
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnOpen.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnOpen.java
------------------------------------------------------------------------------
svn:keywords = Date Revision
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/OnOpen.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/PongMessage.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/PongMessage.java?rev=1492048&view=auto
==============================================================================
--- geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/PongMessage.java (added)
+++ geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/PongMessage.java Wed Jun 12 04:13:29 2013
@@ -0,0 +1,36 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package javax.websocket;
+
+import java.nio.ByteBuffer;
+
+/**
+ * The PongMessage interface represents a web socket pong. PongMessages may be received by using a
+ * MessageHandler.Basic<PongMessage>. The payload of the PongMessage is the application data sent by the peer.
+ */
+public interface PongMessage {
+
+ /**
+ * The application data inside the pong message from the peer.
+ *
+ * @return the application data.
+ */
+ ByteBuffer getApplicationData();
+}
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/PongMessage.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/PongMessage.java
------------------------------------------------------------------------------
svn:keywords = Date Revision
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/PongMessage.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/RemoteEndpoint.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/RemoteEndpoint.java?rev=1492048&view=auto
==============================================================================
--- geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/RemoteEndpoint.java (added)
+++ geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/RemoteEndpoint.java Wed Jun 12 04:13:29 2013
@@ -0,0 +1,334 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package javax.websocket;
+
+import java.io.IOException;
+import java.io.OutputStream;
+import java.io.Writer;
+import java.nio.ByteBuffer;
+import java.util.concurrent.Future;
+
+/**
+ * The RemoteEndpoint object is supplied by the container and represents the 'other end' or peer of the Web Socket
+ * conversation. Instances of the RemoteEndpoint are obtained from the Session using Session.getBasicRemote() or
+ * Session.getAsyncRemote(). Objects of this kind include numerous ways to send web socket messages. There are two kinds
+ * of RemoteEndpoint objects: RemoteEndpoint.Basic for synchronous sending of websocket messages, and
+ * RemoteEndpoint.Async for sending messages asynchronously.
+ * <p/>
+ * There is no guarantee of the successful delivery of a web socket message to the peer, but if the action of sending a
+ * message causes an error known to the container, the API throws it. RemoteEndpoints include a variety of ways to send
+ * messages: by whole message, in parts, and in various data formats including websocket pings and pongs.
+ * <p/>
+ * Implementations may or may not support batching of messages. More detail of the expected semantics of implementations
+ * that do support batching are laid out in setBatchingAllowed(boolean).
+ * <p/>
+ * Note: Implementations may choose their own schemes for sending large messages in smaller parts. These schemes may or
+ * may not bear a relationship to the underlying websocket dataframes in which the message is ultimately sent on the
+ * wire.
+ * <p/>
+ * If the underlying connection is closed and methods on the RemoteEndpoint are attempted to be called, they will result
+ * in an error being generated. For the methods that send messages, this will be an IOException, for the methods that
+ * alter configuration of the endpoint, this will be runtime IllegalArgumentExceptions.
+ */
+public interface RemoteEndpoint {
+
+ /**
+ * This representation of the peer of a web socket conversation has the ability to send messages asynchronously. The
+ * point of completion of the send is defined when all the supplied data has been written to the underlying
+ * connection. The completion handlers for the asynchronous methods are always called with a different thread from
+ * that which initiated the send.
+ */
+ public static interface Async extends RemoteEndpoint {
+ /**
+ * Return the number of milliseconds the implementation will timeout attempting to send a websocket message. A
+ * non-positive number indicates the implementation will not timeout attempting to send a websocket message
+ * asynchronously. This value overrides the default value assigned in the WebSocketContainer.
+ *
+ * @return the timeout time in milliseconds.
+ */
+ long getSendTimeout();
+
+ /**
+ * Sets the number of milliseconds the implementation will timeout attempting to send a websocket message. A
+ * non-positive number indicates the implementation will not timeout attempting to send a websocket message
+ * asynchronously. This value overrides the default value assigned in the WebSocketContainer.
+ *
+ * @param timeoutmillis
+ * The number of milliseconds this RemoteEndpoint will wait before timing out an incomplete
+ * asynchronous message send.
+ */
+ void setSendTimeout(long timeoutmillis);
+
+ /**
+ * Initiates the asynchronous transmission of a text message. This method returns before the message is
+ * transmitted. Developers provide a callback to be notified when the message has been transmitted. Errors in
+ * transmission are given to the developer in the SendResult object.
+ *
+ * @param text
+ * the text being sent.
+ * @param handler
+ * the handler which will be notified of progress.
+ * @throws IllegalArgumentException
+ * - if the text or the handler is null.
+ */
+ void sendText(String text, SendHandler handler);
+
+ /**
+ * Initiates the asynchronous transmission of a text message. This method returns before the message is
+ * transmitted. Developers use the returned Future object to track progress of the transmission. The Future's
+ * get() method returns null upon successful completion. Errors in transmission are wrapped in the
+ * ExecutionException thrown when querying the Future object.
+ *
+ * @param text
+ * the text being sent.
+ * @return the Future object representing the send operation.
+ * @throws IllegalArgumentException
+ * - if the text is null.
+ */
+ Future<Void> sendText(String text);
+
+ /**
+ * Initiates the asynchronous transmission of a binary message. This method returns before the message is
+ * transmitted. Developers use the returned Future object to track progress of the transmission. The Future's
+ * get() method returns null upon successful completion. Errors in transmission are wrapped in the
+ * ExecutionException thrown when querying the Future object.
+ *
+ * @param data
+ * the data being sent.
+ * @return the Future object representing the send operation.
+ * @throws IllegalArgumentException
+ * - if the data is null.
+ */
+ Future<Void> sendBinary(ByteBuffer data);
+
+ /**
+ * Initiates the asynchronous transmission of a binary message. This method returns before the message is
+ * transmitted. Developers provide a callback to be notified when the message has been transmitted. Errors in
+ * transmission are given to the developer in the SendResult object.
+ *
+ * @param data
+ * the data being sent, must not be null.
+ * @param handler
+ * the handler that will be notified of progress, must not be null.
+ * @throws IllegalArgumentException
+ * - if either the data or the handler are null.
+ */
+ void sendBinary(ByteBuffer data, SendHandler handler);
+
+ /**
+ * Initiates the asynchronous transmission of a custom developer object. The developer will have provided an
+ * encoder for this object type in the endpoint configuration. Containers will by default be able to encode java
+ * primitive types and their object equivalents, otherwise the developer must have provided an encoder for the
+ * object type in the endpoint configuration. Progress may be tracked using the Future object. The Future's
+ * get() methods return null upon successful completion. Errors in transmission are wrapped in the
+ * ExecutionException thrown when querying the Future object.
+ *
+ * @param data
+ * the object being sent.
+ * @return the Future object representing the send operation.
+ */
+ Future<Void> sendObject(Object data);
+
+ /**
+ * Initiates the asynchronous transmission of a custom developer object. Containers will by default be able to
+ * encode java primitive types and their object equivalents, otherwise the developer must have provided an
+ * encoder for the object type in the endpoint configuration. Developers are notified when transmission is
+ * complete through the supplied callback object.
+ *
+ * @param data
+ * the object being sent.
+ * @param handler
+ * the handler that will be notified of progress, must not be null.
+ * @throws IllegalArgumentException
+ * - if either the data or the handler are null.
+ */
+ void sendObject(Object data, SendHandler handler);
+ }
+
+ /**
+ * This representation of the peer of a web socket conversation has the ability to send messages synchronously. The
+ * point of completion of the send is defined when all the supplied data has been written to the underlying
+ * connection. The methods for sending messages on the RemoteEndpoint.Basic block until this point of completion is
+ * reached, except for getSendStream and getSendWriter which present traditional blocking I/O streams to write
+ * messages.
+ * <p/>
+ * If the websocket connection underlying this RemoteEndpoint is busy sending a message when a call is made to send
+ * another one, for example if two threads attempt to call a send method concurrently, or if a developer attempts to
+ * send a new message while in the middle of sending an existing one, the send method called while the connection is
+ * already busy may throw an IllegalStateException.
+ */
+ public static interface Basic extends RemoteEndpoint {
+ /**
+ * Send a text message, blocking until all of the message has been transmitted.
+ *
+ * @param text
+ * the message to be sent.
+ * @throws IOException
+ * - if there is a problem delivering the message.
+ * @throws IllegalArgumentException
+ * - if the text is null.
+ */
+ void sendText(String text) throws IOException;
+
+ /**
+ * Send a binary message, returning when all of the message has been transmitted.
+ *
+ * @param data
+ * the message to be sent.
+ * @throws IOException
+ * - if there is a problem delivering the message.
+ * @throws IllegalArgumentException
+ * - if the data is null.
+ */
+ void sendBinary(ByteBuffer data) throws IOException;
+
+ /**
+ * Send a text message in parts, blocking until all of the message has been transmitted. The runtime reads the
+ * message in order. Non-final parts of the message are sent with isLast set to false. The final part must be
+ * sent with isLast set to true.
+ *
+ * @param partialMessage
+ * the parts of the message being sent.
+ * @param isLast
+ * Whether the partial message being sent is the last part of the message.
+ * @throws IOException
+ * - if there is a problem delivering the message fragment.
+ * @throws IllegalArgumentException
+ * - if the partialMessage is null.
+ */
+ void sendText(String partialMessage, boolean isLast) throws IOException;
+
+ /**
+ * Send a binary message in parts, blocking until all of the message has been transmitted. The runtime reads the
+ * message in order. Non-final parts are sent with isLast set to false. The final piece must be sent with isLast
+ * set to true.
+ *
+ * @param partialByte
+ * the part of the message being sent.
+ * @param isLast
+ * Whether the partial message being sent is the last part of the message.
+ * @throws IOException
+ * - if there is a problem delivering the partial message.
+ * @throws IllegalArgumentException
+ * - if the partialByte is null.
+ */
+ void sendBinary(ByteBuffer partialByte, boolean isLast) throws IOException;
+
+ /**
+ * Opens an output stream on which a binary message may be sent. The developer must close the output stream in
+ * order to indicate that the complete message has been placed into the output stream.
+ *
+ * @return the output stream to which the message will be written.
+ * @throws IOException
+ * if there is a problem obtaining the OutputStream to write the binary message.
+ */
+ OutputStream getSendStream() throws IOException;
+
+ /**
+ * Opens an character stream on which a text message may be sent. The developer must close the writer in order
+ * to indicate that the complete message has been placed into the character stream.
+ *
+ * @return the writer to which the message will be written.
+ * @throws IOException
+ * if there is a problem obtaining the Writer to write the text message.
+ */
+ Writer getSendWriter() throws IOException;
+
+ /**
+ * Sends a custom developer object, blocking until it has been transmitted. Containers will by default be able
+ * to encode java primitive types and their object equivalents, otherwise the developer must have provided an
+ * encoder for the object type in the endpoint configuration. A developer-provided encoder for a Java primitive
+ * type overrides the container default encoder.
+ *
+ * @param data
+ * the object to be sent.
+ * @throws IOException
+ * - if there is a communication error sending the message object.
+ * @throws EncodeException
+ * - if there was a problem encoding the message object into the form of a native websocket message.
+ * @throws IllegalArgumentException
+ * - if the data parameter is null
+ */
+ void sendObject(Object data) throws IOException, EncodeException;
+ }
+
+ /**
+ * Indicate to the implementation that it is allowed to batch outgoing messages before sending. Not all
+ * implementations support batching of outgoing messages. The default mode for RemoteEndpoints is false. If the
+ * developer has indicated that batching of outgoing messages is permitted, then the developer must call
+ * flushBatch() in order to be sure that all the messages passed into the send methods of this RemoteEndpoint are
+ * sent. When batching is allowed, the implementations send operations are considered to have completed if the
+ * message has been written to the local batch, in the case when there is still room in the batch for the message,
+ * and are considered to have completed if the batch has been send to the peer and the remainder written to the new
+ * batch, in the case when writing the message causes the batch to need to be sent. The blocking and asynchronous
+ * send methods use this notion of completion in order to complete blocking calls, notify SendHandlers and complete
+ * Futures respectively. When batching is allowed, if the developer has called send methods on this RemoteEndpoint
+ * without calling flushBatch(), then the implementation may not have sent all the messages the developer has asked
+ * to be sent. If the parameter value is false and the implementation has a batch of unsent messages, then the
+ * implementation must immediately send the batch of unsent messages.
+ *
+ * @param allowed
+ * whether the implementation is allowed to batch messages.
+ * @throws IOException
+ * if batching is being disabled and there are unsent messages this error may be thrown as the
+ * implementation sends the batch of unsent messages if there is a problem.
+ */
+ void setBatchingAllowed(boolean allowed) throws IOException;
+
+ /**
+ * Return whether the implementation is allowed to batch outgoing messages before sending. The default mode for
+ * RemoteEndpoints is false. The value may be changed by calling setBatchingAllowed.
+ */
+ boolean getBatchingAllowed();
+
+ /**
+ * This method is only used when batching is allowed for this RemoteEndpint. Calling this method forces the
+ * implementation to send any unsent messages it has been batching.
+ *
+ * @throws IOException
+ */
+ void flushBatch() throws IOException;
+
+ /**
+ * Send a Ping message containing the given application data to the remote endpoint. The corresponding Pong message
+ * may be picked up using the MessageHandler.Pong handler.
+ *
+ * @param applicationData
+ * the data to be carried in the ping request.
+ * @throws IOException
+ * if the ping failed to be sent
+ * @throws IllegalArgumentException
+ * if the applicationData exceeds the maximum allowed payload of 125 bytes
+ */
+ void sendPing(ByteBuffer applicationData) throws IOException, IllegalArgumentException;
+
+ /**
+ * Allows the developer to send an unsolicited Pong message containing the given application data in order to serve
+ * as a unidirectional heartbeat for the session.
+ *
+ * @param applicationData
+ * the application data to be carried in the pong response.
+ * @throws IOException
+ * if the pong failed to be sent
+ * @throws IllegalArgumentException
+ * if the applicationData exceeds the maximum allowed payload of 125 bytes
+ */
+ void sendPong(ByteBuffer applicationData) throws IOException, IllegalArgumentException;
+}
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/RemoteEndpoint.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/RemoteEndpoint.java
------------------------------------------------------------------------------
svn:keywords = Date Revision
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/RemoteEndpoint.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SendHandler.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SendHandler.java?rev=1492048&view=auto
==============================================================================
--- geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SendHandler.java (added)
+++ geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SendHandler.java Wed Jun 12 04:13:29 2013
@@ -0,0 +1,34 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package javax.websocket;
+
+/**
+ * A simple callback object for asynchronous sending of web socket messages.
+ */
+public interface SendHandler {
+
+ /**
+ * Called once the message has been transmitted.
+ *
+ * @param result
+ * the result.
+ */
+ void onResult(SendResult result);
+}
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SendHandler.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SendHandler.java
------------------------------------------------------------------------------
svn:keywords = Date Revision
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SendHandler.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SendResult.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SendResult.java?rev=1492048&view=auto
==============================================================================
--- geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SendResult.java (added)
+++ geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SendResult.java Wed Jun 12 04:13:29 2013
@@ -0,0 +1,64 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package javax.websocket;
+
+/**
+ * The result of asynchronously sending a web socket message. A SendResult is either ok indicating there was no problem,
+ * or is not OK in which case there was a problem and it carries an exception to indicate what the problem was.
+ */
+public class SendResult {
+
+ private final Throwable exception;
+
+ /**
+ * Construct a SendResult signifying a successful send carrying no exception.
+ */
+ public SendResult() {
+ exception = null;
+ }
+
+ /**
+ * Construct a SendResult carrying an exception.
+ *
+ * @param exception
+ * the exception causing a send failure.
+ */
+ public SendResult(Throwable exception) {
+ this.exception = exception;
+ }
+
+ /**
+ * The problem sending the message.
+ *
+ * @return the problem or null if the send was successful.
+ */
+ public Throwable getException() {
+ return this.exception;
+ }
+
+ /**
+ * Determines if this result is ok or not.
+ *
+ * @return whether the send was successful or not.
+ */
+ public boolean isOK() {
+ return this.exception == null;
+ }
+}
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SendResult.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SendResult.java
------------------------------------------------------------------------------
svn:keywords = Date Revision
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SendResult.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/Session.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/Session.java?rev=1492048&view=auto
==============================================================================
--- geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/Session.java (added)
+++ geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/Session.java Wed Jun 12 04:13:29 2013
@@ -0,0 +1,283 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package javax.websocket;
+
+import java.io.Closeable;
+import java.io.IOException;
+import java.net.URI;
+import java.security.Principal;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * A Web Socket session represents a conversation between two web socket endpoints. As soon as the websocket handshake
+ * completes successfully, the web socket implementation provides the endpoint an open websocket session. The endpoint
+ * can then register interest in incoming messages that are part of this newly created session by providing a
+ * MessageHandler to the session, and can send messages to the other end of the conversation by means of the
+ * RemoteEndpoint object obtained from this session.
+ * <p/>
+ * Once the session is closed, it is no longer valid for use by applications. Calling any of its methods (with the
+ * exception of the close() methods) once the session has been closed will result in an IllegalStateException being
+ * thrown. Developers should retrieve any information from the session during the
+ * Endpoint.onClose(javax.websocket.Session, javax.websocket.CloseReason) method. Following the convention of Closeable
+ * calling the Session close() methods after the Session has been closed has no effect.
+ * <p/>
+ * Session objects may be called by multiple threads. Implementations must ensure the integrity of the mutable
+ * properties of the session under such circumstances.
+ */
+public interface Session extends Closeable {
+
+ /**
+ * Return the container that this session is part of.
+ *
+ * @return the container.
+ */
+ WebSocketContainer getContainer();
+
+ /**
+ * Register to handle to incoming messages in this conversation. A maximum of one message handler per native
+ * websocket message type (text, binary, pong) may be added to each Session. I.e. a maximum of one message handler
+ * to handle incoming text messages a maximum of one message handler for handling incoming binary messages, and a
+ * maximum of one for handling incoming pong messages. For further details of which message handlers handle which of
+ * the native websocket message types please see MessageHandler.Whole and MessageHandler.Partial. Adding more than
+ * one of any one type will result in a runtime exception.
+ * <p/>
+ * See Endpoint for a usage example.
+ *
+ * @param handler
+ * the MessageHandler to be added.
+ * @throws IllegalStateException
+ * if there is already a MessageHandler registered for the same native websocket message type as this
+ * handler.
+ */
+ void addMessageHandler(MessageHandler handler) throws IllegalStateException;
+
+ /**
+ * Return an unmodifiable copy of the set of MessageHandlers for this Session.
+ *
+ * @return the set of message handlers.
+ */
+ Set<MessageHandler> getMessageHandlers();
+
+ /**
+ * Remove the given MessageHandler from the set belonging to this session. This method may block if the given
+ * handler is processing a message until it is no longer in use.
+ *
+ * @param handler
+ * the handler to be removed.
+ */
+ void removeMessageHandler(MessageHandler handler);
+
+ /**
+ * Returns the version of the websocket protocol currently being used. This is taken as the value of the
+ * Sec-WebSocket-Version header used in the opening handshake. i.e. "13".
+ *
+ * @return the protocol version.
+ */
+ String getProtocolVersion();
+
+ /**
+ * Return the sub protocol agreed during the websocket handshake for this conversation.
+ *
+ * @return the negotiated subprotocol, or the empty string if there isn't one.
+ */
+ String getNegotiatedSubprotocol();
+
+ /**
+ * Return the list of extensions currently in use for this conversation.
+ *
+ * @return the negotiated extensions.
+ */
+ List<Extension> getNegotiatedExtensions();
+
+ /**
+ * Return true if and only if the underlying socket is using a secure transport.
+ *
+ * @return whether its using a secure transport.
+ */
+ boolean isSecure();
+
+ /**
+ * Return true if and only if the underlying socket is open.
+ *
+ * @return whether the session is active.
+ */
+ boolean isOpen();
+
+ /**
+ * Return the number of milliseconds before this conversation may be closed by the container if it is inactive, i.e.
+ * no messages are either sent or received in that time.
+ *
+ * @return the timeout in milliseconds.
+ */
+ long getMaxIdleTimeout();
+
+ /**
+ * Set the non-zero number of milliseconds before this session will be closed by the container if it is inactive, ie
+ * no messages are either sent or received. A value that is 0 or negative indicates the session will never timeout
+ * due to inactivity.
+ *
+ * @param milliseconds
+ * the number of milliseconds.
+ */
+ void setMaxIdleTimeout(long milliseconds);
+
+ /**
+ * Sets the maximum length of incoming binary messages that this Session can buffer.
+ *
+ * @param length
+ * the maximum length.
+ */
+ void setMaxBinaryMessageBufferSize(int length);
+
+ /**
+ * The maximum length of incoming binary messages that this Session can buffer. If the implementation receives a
+ * binary message that it cannot buffer because it is too large, it must close the session with a close code of
+ * CloseReason.CloseCodes.TOO_BIG.
+ *
+ * @return the maximum binary message size that can be buffered.
+ */
+ int getMaxBinaryMessageBufferSize();
+
+ /**
+ * Sets the maximum length of incoming text messages that this Session can buffer.
+ *
+ * @param length
+ * the maximum length.
+ */
+ void setMaxTextMessageBufferSize(int length);
+
+ /**
+ * The maximum length of incoming text messages that this Session can buffer. If the implementation receives a text
+ * message that it cannot buffer because it is too large, it must close the session with a close code of
+ * CloseReason.CloseCodes.TOO_BIG.
+ *
+ * @return the maximum text message size that can be buffered.
+ */
+ int getMaxTextMessageBufferSize();
+
+ /**
+ * Return a reference a RemoteEndpoint object representing the peer of this conversation that is able to send
+ * messages asynchronously to the peer.
+ *
+ * @return the remote endpoint.
+ */
+ RemoteEndpoint.Async getAsyncRemote();
+
+ /**
+ * Return a reference a RemoteEndpoint object representing the peer of this conversation that is able to send
+ * messages synchronously to the peer.
+ *
+ * @return the remote endpoint.
+ */
+ RemoteEndpoint.Basic getBasicRemote();
+
+ /**
+ * Returns a string containing the unique identifier assigned to this session. The identifier is assigned by the web
+ * socket implementation and is implementation dependent.
+ *
+ * @return the unique identifier for this session instance.
+ */
+ String getId();
+
+ /**
+ * Close the current conversation with a normal status code and no reason phrase.
+ *
+ * @throws IOException
+ * - if there was a connection error closing the connection.
+ */
+ @Override
+ void close() throws IOException;
+
+ /**
+ * Close the current conversation, giving a reason for the closure. The close call causes the implementation to
+ * attempt notify the client of the close as soon as it can. This may cause the sending of unsent messages
+ * immediately prior to the close notification. After the close notification has been sent the implementation
+ * notifies the endpoint's onClose method. Note the websocket specification defines the acceptable uses of status
+ * codes and reason phrases. If the application cannot determine a suitable close code to use for the closeReason,
+ * it is recommended to use CloseReason.CloseCodes.NO_STATUS_CODE.
+ *
+ * @param closeReason
+ * the reason for the closure.
+ * @throws IOException
+ * if there was a connection error closing the connection
+ */
+ void close(CloseReason closeReason) throws IOException;
+
+ /**
+ * Return the URI under which this session was opened, including the query string if there is one.
+ *
+ * @return the request URI.
+ */
+ URI getRequestURI();
+
+ /**
+ * Return the request parameters associated with the request this session was opened under.
+ *
+ * @return the unmodifiable map of the request parameters.
+ */
+ Map<String, List<String>> getRequestParameterMap();
+
+ /**
+ * Return the query string associated with the request this session was opened under.
+ *
+ * @return the query string
+ */
+ String getQueryString();
+
+ /**
+ * Return a map of the path parameter names and values used associated with the request this session was opened
+ * under.
+ *
+ * @return the unmodifiable map of path parameters. The key of the map is the parameter name, the values in the map
+ * are the parameter values.
+ */
+ Map<String, String> getPathParameters();
+
+ /**
+ * While the session is open, this method returns a Map that the developer may use to store application specific
+ * information relating to this session instance. The developer may retrieve information from this Map at any time
+ * between the opening of the session and during the onClose() method. But outside that time, any information stored
+ * using this Map may no longer be kept by the container. Web socket applications running on distributed
+ * implementations of the web container should make any application specific objects stored here
+ * java.io.Serializable, or the object may not be recreated after a failover.
+ *
+ * @return an editable Map of application data.
+ */
+ Map<String, Object> getUserProperties();
+
+ /**
+ * Return the authenticated user for this Session or null if no user is authenticated for this session.
+ *
+ * @return the user principal.
+ */
+ Principal getUserPrincipal();
+
+ /**
+ * Return a copy of the Set of all the open web socket sessions that represent connections to the same endpoint to
+ * which this session represents a connection. The Set includes the session this method is called on. These sessions
+ * may not still be open at any point after the return of this method. For example, iterating over the set at a
+ * later time may yield one or more closed sessions. Developers should use session.isOpen() to check.
+ *
+ * @return the set of sessions, open at the time of return.
+ */
+ Set<Session> getOpenSessions();
+}
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/Session.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/Session.java
------------------------------------------------------------------------------
svn:keywords = Date Revision
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/Session.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SessionException.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SessionException.java?rev=1492048&view=auto
==============================================================================
--- geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SessionException.java (added)
+++ geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SessionException.java Wed Jun 12 04:13:29 2013
@@ -0,0 +1,54 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package javax.websocket;
+
+/**
+ * A SessionException represents a general exception type reporting problems occurring on a websocket session.
+ */
+public class SessionException extends Exception {
+ private static final long serialVersionUID = -5781258978872105957L;
+
+ private final Session session;
+
+ /**
+ * Creates a new instance of this exception with the given message, the wrapped cause of the exception and the
+ * session with which the problem is associated.
+ *
+ * @param message
+ * a description of the problem
+ * @param cause
+ * the error that caused the problem
+ * @param session
+ * the session on which the problem occurred.
+ */
+ public SessionException(String message, Throwable cause, Session session) {
+ super(message, cause);
+ this.session = session;
+ }
+
+ /**
+ * Return the Session on which the problem occurred.
+ *
+ * @return the session
+ */
+ public Session getSession() {
+ return this.session;
+ }
+}
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SessionException.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SessionException.java
------------------------------------------------------------------------------
svn:keywords = Date Revision
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/SessionException.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/WebSocketContainer.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/WebSocketContainer.java?rev=1492048&view=auto
==============================================================================
--- geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/WebSocketContainer.java (added)
+++ geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/WebSocketContainer.java Wed Jun 12 04:13:29 2013
@@ -0,0 +1,207 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package javax.websocket;
+
+import java.io.IOException;
+import java.net.URI;
+import java.util.Set;
+
+/**
+ * A WebSocketContainer is an implementation provided object that provides applications a view on the container running
+ * it. The WebSocketContainer container various configuration parameters that control default session and buffer
+ * properties of the endpoints it contains. It also allows the developer to deploy websocket client endpoints by
+ * initiating a web socket handshake from the provided endpoint to a supplied URI where the peer endpoint is presumed to
+ * reside.
+ * <p/>
+ * A WebSocketContainer may be accessed by concurrent threads, so implementations must ensure the integrity of its
+ * mutable attributes in such circumstances.
+ */
+public interface WebSocketContainer {
+
+ /**
+ * Return the number of milliseconds the implementation will timeout attempting to send a websocket message for all
+ * RemoteEndpoints associated with this container. A non-positive number indicates the implementation will not
+ * timeout attempting to send a websocket message asynchronously. Note this default may be overridden in each
+ * RemoteEndpoint.
+ *
+ * @return the timeout time in milliseconds.
+ */
+ long getDefaultAsyncSendTimeout();
+
+ /**
+ * Sets the number of milliseconds the implementation will timeout attempting to send a websocket message for all
+ * RemoteEndpoints associated with this container. A non-positive number indicates the implementation will not
+ * timeout attempting to send a websocket message asynchronously. Note this default may be overridden in each
+ * RemoteEndpoint.
+ *
+ * @param timeoutmillis
+ */
+ void setAsyncSendTimeout(long timeoutmillis);
+
+ /**
+ * Connect the supplied annotated endpoint instance to its server. The supplied object must be a class decorated
+ * with the class level ServerEndpoint annotation. This method blocks until the connection is established, or throws
+ * an error if either the connection could not be made or there was a problem with the supplied endpoint class. If
+ * the developer uses this method to deploy the client endpoint, services like dependency injection that are
+ * supported, for example, when the implementation is part of the Java EE platform may not be available. If the
+ * client endpoint uses dependency injection, use connectToServer(java.lang.Class, java.net.URI) instead.
+ *
+ * @param annotatedEndpointInstance
+ * the annotated websocket client endpoint instance.
+ * @param path
+ * the complete path to the server endpoint.
+ * @return the Session created if the connection is successful.
+ * @throws DeploymentException
+ * if the annotated endpoint instance is not valid.
+ * @throws IOException
+ * if there was a network or protocol problem that prevented the client endpoint being connected to its
+ * server.
+ * @throws IllegalStateException
+ * if called during the deployment phase of the containing application.
+ */
+ Session connectToServer(Object annotatedEndpointInstance, URI path) throws DeploymentException, IOException;
+
+ /**
+ * Connect the supplied annotated endpoint to its server. The supplied object must be a class decorated with the
+ * class level ServerEndpoint annotation. This method blocks until the connection is established, or throws an error
+ * if either the connection could not be made or there was a problem with the supplied endpoint class.
+ *
+ * @param annotatedEndpointClass
+ * the annotated websocket client endpoint.
+ * @param path
+ * the complete path to the server endpoint.
+ * @return the Session created if the connection is successful.
+ * @throws DeploymentException
+ * if the class is not a valid annotated endpoint class.
+ * @throws IOException
+ * if there was a network or protocol problem that prevented the client endpoint being connected to its
+ * server.
+ * @throws IllegalStateException
+ * if called during the deployment phase of the containing application.
+ */
+ Session connectToServer(Class<?> annotatedEndpointClass, URI path) throws DeploymentException, IOException;
+
+ /**
+ * Connect the supplied programmatic client endpoint instance to its server with the given configuration. This
+ * method blocks until the connection is established, or throws an error if the connection could not be made. If the
+ * developer uses this method to deploy the client endpoint, services like dependency injection that are supported,
+ * for example, when the implementation is part of the Java EE platform may not be available. If the client endpoint
+ * uses dependency injection, use connectToServer(java.lang.Class, javax.websocket.ClientEndpointConfig,
+ * java.net.URI) instead.
+ *
+ * @param endpointInstance
+ * the programmatic client endpoint instance Endpoint.
+ * @param cec
+ * the configuration used to configure the programmatic endpoint.
+ * @param path
+ * the complete path to the server endpoint.
+ * @return the Session created if the connection is successful.
+ * @throws DeploymentException
+ * if the configuration is not valid
+ * @throws IOException
+ * if there was a network or protocol problem that prevented the client endpoint being connected to its
+ * server
+ * @throws IllegalStateException
+ * if called during the deployment phase of the containing application.
+ */
+ Session connectToServer(Endpoint endpointInstance, ClientEndpointConfig cec, URI path) throws DeploymentException,
+ IOException;
+
+ /**
+ * Connect the supplied programmatic endpoint to its server with the given configuration. This method blocks until
+ * the connection is established, or throws an error if the connection could not be made.
+ *
+ * @param endpointClass
+ * the programmatic client endpoint class Endpoint.
+ * @param cec
+ * the configuration used to configure the programmatic endpoint.
+ * @param path
+ * the complete path to the server endpoint.
+ * @return the Session created if the connection is successful.
+ * @throws DeploymentException
+ * if the configuration is not valid
+ * @throws IOException
+ * if there was a network or protocol problem that prevented the client endpoint being connected to its
+ * server
+ * @throws IllegalStateException
+ * if called during the deployment phase of the containing application.
+ */
+ Session connectToServer(Class<? extends Endpoint> endpointClass, ClientEndpointConfig cec, URI path)
+ throws DeploymentException, IOException;
+
+ /**
+ * Return the default time in milliseconds after which any web socket sessions in this container will be closed if
+ * it has been inactive. A value that is 0 or negative indicates the sessions will never timeout due to inactivity.
+ * The value may be overridden on a per session basis using Session.setMaxIdleTimeout(long)
+ *
+ * @return the default number of milliseconds after which an idle session in this container will be closed
+ */
+ long getDefaultMaxSessionIdleTimeout();
+
+ /**
+ * Sets the default time in milliseconds after which any web socket sessions in this container will be closed if it
+ * has been inactive. A value that is 0 or negative indicates the sessions will never timeout due to inactivity. The
+ * value may be overridden on a per session basis using Session.setMaxIdleTimeout(long)
+ *
+ * @param tmeout
+ * the maximum time in milliseconds.
+ */
+ void setDefaultMaxSessionIdleTimeout(long tmeout);
+
+ /**
+ * Returns the default maximum size of incoming binary message that this container will buffer. This default may be
+ * overridden on a per session basis using Session.setMaxBinaryMessageBufferSize(int)
+ *
+ * @return the maximum size of incoming binary message in number of bytes.
+ */
+ int getDefaultMaxBinaryMessageBufferSize();
+
+ /**
+ * Sets the default maximum size of incoming binary message that this container will buffer.
+ *
+ * @param max
+ * the maximum size of binary message in number of bytes.
+ */
+ void setDefaultMaxBinaryMessageBufferSize(int max);
+
+ /**
+ * Returns the default maximum size of incoming text message that this container will buffer. This default may be
+ * overridden on a per session basis using Session.setMaxTextMessageBufferSize(int)
+ *
+ * @return the maximum size of incoming text message in number of bytes.
+ */
+ int getDefaultMaxTextMessageBufferSize();
+
+ /**
+ * Sets the maximum size of incoming text message that this container will buffer.
+ *
+ * @param max
+ * the maximum size of text message in number of bytes.
+ */
+ void setDefaultMaxTextMessageBufferSize(int max);
+
+ /**
+ * Return the set of Extensions installed in the container.
+ *
+ * @return the set of extensions.
+ */
+ Set<Extension> getInstalledExtensions();
+
+}
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/WebSocketContainer.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/WebSocketContainer.java
------------------------------------------------------------------------------
svn:keywords = Date Revision
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/WebSocketContainer.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/HandshakeRequest.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/HandshakeRequest.java?rev=1492048&view=auto
==============================================================================
--- geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/HandshakeRequest.java (added)
+++ geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/HandshakeRequest.java Wed Jun 12 04:13:29 2013
@@ -0,0 +1,109 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package javax.websocket.server;
+
+import java.net.URI;
+import java.security.Principal;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * The handshake request represents the web socket defined Http GET request for the opening handshake of a web socket
+ * session.
+ */
+public interface HandshakeRequest {
+
+ /**
+ * The Sec-WebSocket-Extensions header name
+ */
+ static final String SEC_WEBSOCKET_EXTENSIONS = "Sec-WebSocket-Extensions";
+
+ /**
+ * The Sec-WebSocket-Key header name
+ */
+ static final String SEC_WEBSOCKET_KEY = "Sec-WebSocket-Key";
+
+ /**
+ * The Sec-WebSocket-Protocol header name
+ */
+ static final String SEC_WEBSOCKET_PROTOCOL = "Sec-WebSocket-Protocol";
+
+ /**
+ * The Sec-WebSocket-Version header name
+ */
+ static final String SEC_WEBSOCKET_VERSION = "Sec-WebSocket-Version";
+
+ /**
+ * Return the read only Map of Http Headers that came with the handshake request. The header names are case
+ * insensitive.
+ *
+ * @return the list of headers
+ */
+ Map<String, List<String>> getHeaders();
+
+ /**
+ * Return a reference to the HttpSession that the web socket handshake that started this conversation was part of,
+ * if the implementation is part of a Java EE web container.
+ *
+ * @return the http session or null if either the websocket implementation is not part of a Java EE web container,
+ * or there is no HttpSession associated with the opening handshake request.
+ */
+ Object getHttpSession();
+
+ /**
+ * Return the request parameters associated with the request.
+ *
+ * @return the unmodifiable map of the request parameters.
+ */
+ Map<String, List<String>> getParameterMap();
+
+ /**
+ * Return the query string associated with the request.
+ *
+ * @return the query string
+ */
+ String getQueryString();
+
+ /**
+ * Return the request URI of the handshake request.
+ *
+ * @return the request uri of the handshake request.
+ */
+ URI getRequestURI();
+
+ /**
+ * Return the authenticated user or null if no user is authenticated for this handshake.
+ *
+ * @return the user principal
+ */
+ Principal getUserPrincipal();
+
+ /**
+ * Checks whether the current user is in the given role. Roles and role membership can be defined using deployment
+ * descriptors of the containing WAR file, if running in a Java EE web container. If the user has not been
+ * authenticated, the method returns false.
+ *
+ * @param role
+ * the role being checked.
+ * @return whether the authenticated user is in the role, or false if the user has not been authenticated.
+ */
+ boolean isUserInRole(String role);
+
+}
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/HandshakeRequest.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/HandshakeRequest.java
------------------------------------------------------------------------------
svn:keywords = Date Revision
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/HandshakeRequest.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/PathParam.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/PathParam.java?rev=1492048&view=auto
==============================================================================
--- geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/PathParam.java (added)
+++ geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/PathParam.java Wed Jun 12 04:13:29 2013
@@ -0,0 +1,62 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package javax.websocket.server;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotation may be used to annotate method parameters on server endpoints where a URI-template has been used in
+ * the path-mapping of the ServerEndpoint annotation. The method parameter may be of type String, any Java primitive
+ * type or any boxed version thereof. If a client URI matches the URI-template, but the requested path parameter cannot
+ * be decoded, then the websocket's error handler will be called.
+ * <p/>
+ * For example:-
+ * <p/>
+ * <code>
+ *
+ * @ServerEndpoint("/bookings/{guest-id ") public class BookingServer {
+ *
+ * @OnMessage public void processBookingRequest(@PathParam("guest-id") String guestID, String message, Session session)
+ * { // process booking from the given guest here } } </code>
+ * <p/>
+ * For example:-
+ * <p/>
+ * <code>
+ * @ServerEndpoint("/rewards/{vip-level ") public class RewardServer {
+ *
+ * @OnMessage public void processReward(@PathParam("vip-level") Integer vipLevel, String message, Session session) {
+ * // process reward here } } </code>
+ *
+ */
+@Retention(value = RetentionPolicy.RUNTIME)
+@Target(value = ElementType.PARAMETER)
+public @interface PathParam {
+
+ /**
+ * The name of the variable used in the URI-template. If the name does not match a path variable in the
+ * URI-template, the value of the method parameter this annotation annotates is null.
+ *
+ * @return the name of the variable used in the URI-template.
+ */
+ public String value();
+}
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/PathParam.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/PathParam.java
------------------------------------------------------------------------------
svn:keywords = Date Revision
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/PathParam.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/ServerApplicationConfig.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/ServerApplicationConfig.java?rev=1492048&view=auto
==============================================================================
--- geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/ServerApplicationConfig.java (added)
+++ geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/ServerApplicationConfig.java Wed Jun 12 04:13:29 2013
@@ -0,0 +1,46 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package javax.websocket.server;
+
+import java.util.Set;
+
+import javax.websocket.Endpoint;
+
+/**
+ * Developers include implementations of ServerApplicationConfig in an archive containing websocket endpoints (WAR file, or JAR file within the WAR file) in order to specify the websocket endpoints within the archive the implementation must deploy. There is a separate method for programmatic endpoints and for annotated endpoints.
+ */
+public interface ServerApplicationConfig {
+
+ /**
+ * Return a set of annotated endpoint classes that the server container must deploy. The set of classes passed in to this method is the set obtained by scanning the archive containing the implementation of this interface. Therefore, this set passed in contains all the annotated endpoint classes in the JAR or WAR file containing the implementation of this interface. This set passed in may be used the build the set to return to the container for deployment.
+ *
+ * @param scanned the set of all the annotated endpoint classes in the archive containing the implementation of this interface.
+ * @return the non-null set of annotated endpoint classes to deploy on the server, using the empty set to indicate none.
+ */
+ Set<Class<?>> getAnnotatedEndpointClasses(Set<Class<?>> scanned);
+
+ /**
+ * Return a set of ServerEndpointConfig instances that the server container will use to deploy the programmatic endpoints. The set of Endpoint classes passed in to this method is the set obtained by scanning the archive containing the implementation of this ServerApplicationConfig. This set passed in may be used the build the set of ServerEndpointConfig instances to return to the container for deployment.
+ *
+ * @param endpointClasses the set of all the Endpoint classes in the archive containing the implementation of this interface.
+ * @return the non-null set of ServerEndpointConfig s to deploy on the server, using the empty set to indicate none.
+ */
+ Set<ServerEndpointConfig> getEndpointConfigs(Set<Class<? extends Endpoint>> endpointClasses);
+}
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/ServerApplicationConfig.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/ServerApplicationConfig.java
------------------------------------------------------------------------------
svn:keywords = Date Revision
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/ServerApplicationConfig.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/ServerContainer.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/ServerContainer.java?rev=1492048&view=auto
==============================================================================
--- geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/ServerContainer.java (added)
+++ geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/ServerContainer.java Wed Jun 12 04:13:29 2013
@@ -0,0 +1,69 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package javax.websocket.server;
+
+import javax.websocket.DeploymentException;
+import javax.websocket.WebSocketContainer;
+
+/**
+ * The ServerContainer is the specialized view of the WebSocketContainer available in server-side deployments. There is
+ * one ServerContainer instance per websocket application. The ServerContainer holds the methods to be able to register
+ * server endpoints during the initialization phase of the application.
+ * <p/>
+ * For websocket enabled web containers, developers may obtain a reference to the ServerContainer instance by retrieving
+ * it as an attribute named javax.websocket.server.ServerContainer on the ServletContext. This way, the registration
+ * methods held on this interface may be called to register server endpoints from a ServletContextListener during the
+ * deployment of the WAR file containing the endpoint.
+ * <p/>
+ * WebSocket implementations that run outside the web container may have other means by which to provide a
+ * ServerContainer instance to the developer at application deployment time.
+ * <p/>
+ * Once the application deployment phase is complete, and the websocket application has begun accepting incoming
+ * connections, the registration methods may no longer be called.
+ */
+public interface ServerContainer extends WebSocketContainer {
+
+ /**
+ * Deploys the given annotated endpoint into this ServerContainer during the initialization phase of deploying the
+ * application.
+ *
+ * @param endpointClass
+ * the class of the annotated endpoint
+ * @throws DeploymentException
+ * if the annotated endpoint was badly formed.
+ * @throws IllegalStateException
+ * - if the containing websocket application has already been deployed.
+ */
+ void addEndpoint(Class<?> endpointClass) throws DeploymentException;
+
+ /**
+ * Deploys the given endpoint configuration into this ServerContainer during the initialization phase of deploying
+ * the application.
+ *
+ * @param serverConfig
+ * the configuration instance representing the logical endpoint that will be registered.
+ * @throws DeploymentException
+ * if the annotated endpoint was badly formed.
+ * @throws IllegalStateException
+ * - if the containing websocket application has already been deployed.
+ */
+ void addEndpoint(ServerEndpointConfig serverConfig) throws DeploymentException;
+
+}
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/ServerContainer.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/ServerContainer.java
------------------------------------------------------------------------------
svn:keywords = Date Revision
Propchange: geronimo/specs/trunk/geronimo-websockets_1.0_spec/src/main/java/javax/websocket/server/ServerContainer.java
------------------------------------------------------------------------------
svn:mime-type = text/plain