org.atmosphere.vibe.ServerSocket Maven / Gradle / Ivy
/*
* Copyright 2014 The Vibe Project
*
* Licensed 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 org.atmosphere.vibe;
import java.net.URI;
import java.util.List;
import java.util.Map;
import java.util.Set;
import org.atmosphere.vibe.platform.action.Action;
import org.atmosphere.vibe.transport.ServerTransport;
/**
* Interface used to interact with the remote socket.
*
* {@code ServerSocket} produced by {@link Server} is used to send and receive
* event to and from the remote socket. The normal usage to use
* {@code ServerSocket} is to create a socket action and pass it to
* {@link Server}. If you are going to hold a reference on {@code ServerSocket},
* you should do something when it is closed through
* {@link ServerSocket#closeAction(Action)}.
*
* Sockets may be accessed by multiple threads.
*
* @author Donghwan Kim
*/
public interface ServerSocket extends AbstractServerSocket {
/**
* A URI used to connect. To work with URI parts, use {@link URI} or
* something like that.
*/
String uri();
/**
* A modifiable set of tag names.
*/
Set tags();
/**
* Adds a given event handler for a given event.
*
* The allowed types for {@code T} are Java types corresponding to JSON
* types.
*
*
*
* JSON
* Java
*
*
*
* Number
* {@link Integer} or {@link Double}
*
*
* String
* {@link String}
*
*
* Boolean
* {@link Boolean}
*
*
* Array
* {@link List}, {@code List} in generic
*
*
* Object
* {@link Map}, {@code Map} in generic
*
*
* null
* {@code null}, {@link Void} for convenience
*
*
*
*
* If the counterpart sends an event with callback, {@code T} should be
* {@link Reply}.
*/
ServerSocket on(String event, Action action);
/**
* Executed if the socket is closed for any reason. Equivalent to
* socket.on("close", action)
*/
ServerSocket closeAction(Action action);
/**
* Executed if there was any error on the socket. You don't need to close it
* explicitly on error event. Equivalent to
* socket.on("error", action)
*/
ServerSocket errorAction(Action action);
/**
* Removes a given event handler for a given event.
*/
ServerSocket off(String event, Action action);
/**
* Sends a given event with data attaching resolved callback.
*
* For the allowed types for {@code T}, see
* {@link ServerSocket#on(String, Action)}.
*/
ServerSocket send(String event, Object data, Action resolved);
/**
* Sends a given event with data attaching resolved callback and rejected
* callback.
*
* For the allowed types for {@code T}, see
* {@link ServerSocket#on(String, Action)}.
*/
ServerSocket send(String event, Object data, Action resolved, Action rejected);
/**
* Returns the underlying component. {@link ServerTransport} is available.
*/
T unwrap(Class clazz);
/**
* Interface to deal with reply.
*
* For the allowed types for {@code T}, see {@link ServerSocket#on(String, Action)}.
*
* @author Donghwan Kim
*/
interface Reply {
/**
* The original data.
*/
T data();
/**
* Resolves.
*/
void resolve();
/**
* Resolves with the value.
*/
void resolve(Object data);
/**
* Rejects.
*/
void reject();
/**
* Rejects with the reason.
*/
void reject(Object error);
}
}