001/*
002 * Copyright 2012-2014 Donghwan Kim
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package io.github.flowersinthesand.portal;
017
018import io.github.flowersinthesand.wes.Action;
019
020import java.net.URI;
021import java.util.List;
022import java.util.Map;
023import java.util.Set;
024
025/**
026 * {@code Socket} is a connectivity between the two portal endpoints.
027 * <p>
028 * Do not hold a reference on {@code Socket} unless the reference shares the
029 * same life cycle with it. It makes things complicated since it is stateful and
030 * also may result in a problem in clustered environment. Always create a socket
031 * action and pass it to {@link Server} to access {@code Socket}.
032 * <p>
033 * Sockets may be accessed by multiple threads.
034 * 
035 * @author Donghwan Kim
036 */
037public interface Socket {
038
039    /**
040     * A unique identifier in the form of UUID generated by client by default.
041     */
042    String id();
043
044    /**
045     * A URI used to connect. To work with URI parts, use {@link URI} or
046     * something like that.
047     */
048    String uri();
049
050    /**
051     * A set of tag names. It's modifiable, deal with it as a plain set.
052     */
053    Set<String> tags();
054
055    /**
056     * Adds a given event handler for a given event.
057     * <p>
058     * The allowed types for {@code T} are Java types corresponding to JSON types.
059     * <table>
060     * <thead>
061     * <tr>
062     * <th>JSON</th>
063     * <th>Java</th>
064     * </tr>
065     * </thead>
066     * <tbody>
067     * <tr>
068     * <td>Number</td>
069     * <td>{@link Integer} or {@link Double}</td>
070     * </tr>
071     * <tr>
072     * <td>String</td>
073     * <td>{@link String}</td>
074     * </tr>
075     * <tr>
076     * <td>Boolean</td>
077     * <td>{@link Boolean}</td>
078     * </tr>
079     * <tr>
080     * <td>Array</td>
081     * <td>{@link List}, {@code List<T>} in generic</td>
082     * </tr>
083     * <tr>
084     * <td>Object</td>
085     * <td>{@link Map}, {@code Map<String, T>} in generic</td>
086     * </tr>
087     * <tr>
088     * <td>null</td>
089     * <td>{@code null}, {@link Void} for convenience</td>
090     * </tr>
091     * </tbody>
092     * </table>
093     * 
094     * If the counterpart sends an event with callback, {@code T} should be {@link Reply}.
095     */
096    <T> Socket on(String event, Action<T> action);
097
098    /**
099     * Removes a given added event handler for a given event.
100     */
101    <T> Socket off(String event, Action<T> action);
102
103    /**
104     * Sends a given event without data.
105     */
106    Socket send(String event);
107
108    /**
109     * Sends a given event with data.
110     */
111    Socket send(String event, Object data);
112
113    /**
114     * Sends a given event with data registering callback.
115     * <p>
116     * For the allowed types for {@code T}, see {@link Socket#on(String, Action)}. 
117     */
118    <T> Socket send(String event, Object data, Action<T> reply);
119
120    /**
121     * Closes the session.
122     */
123    Socket close();
124
125    /**
126     * Interface to deal with reply.
127     * <p>
128     * For the allowed types for {@code T}, see {@link Socket#on(String, Action)}. 
129     * 
130     * @author Donghwan Kim
131     */
132    interface Reply<T> {
133
134        /**
135         * The original data.
136         */
137        T data();
138
139        /**
140         * Replies with success.
141         */
142        void done();
143
144        /**
145         * Replies with success attaching data.
146         */
147        void done(Object data);
148
149        /**
150         * Replies with failure.
151         */
152        void fail();
153
154        /**
155         * Replies with failure attaching data.
156         */
157        void fail(Object error);
158
159    }
160
161}