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;
019import io.github.flowersinthesand.wes.ServerHttpExchange;
020import io.github.flowersinthesand.wes.ServerWebSocket;
021
022/**
023 * Interface used to interact with the socket.
024 * <p>
025 * A {@code Server} instance provides {@link Socket} processing HTTP request and
026 * WebSocket under the specific URI pattern and manages their life cycles. The
027 * {@code Server} API is used to accept socket and to find socket by id and tag.
028 * If you are using dependency injection support, make a {@code Server} as
029 * component and inject it wherever you need to handle socket.
030 * <p>
031 * The {@code Server} is a wes application so can be installed on any platform
032 * like Servlet wes supports. For that reason, {@code Server} doesn't concern
033 * I/O details and I/O details should be configured in the platform following
034 * its policy.
035 * <p>
036 * Server may be accessed by multiple threads.
037 * 
038 * @author Donghwan Kim
039 * @see <a
040 *      href="https://github.com/flowersinthesand/portal-java-examples/tree/master/server/platform/"
041 *      target="_parent">Examples to install portal</a>
042 */
043public interface Server {
044
045    /**
046     * Returns a sentence that all of the socket in this server or all of the
047     * server if it's in a clustered environment have to follow.
048     */
049    Sentence all();
050
051    /**
052     * Executes the given action retrieving all of the socket in this server or
053     * all of the server if it's in a clustered environment .
054     */
055    Server all(Action<Socket> action);
056
057    /**
058     * Returns a sentence that the socket of the given id in this server or all
059     * of the server if it's in a clustered environment have to follow.
060     */
061    Sentence byId(String id);
062
063    /**
064     * Executes the given action retrieving the socket of the given id in this
065     * server or all of the server if it's in a clustered environment. The given
066     * action will be executed only once if socket is found and won't be
067     * executed if not found.
068     */
069    Server byId(String id, Action<Socket> action);
070
071    /**
072     * Returns a sentence that the socket tagged with all of the given names in
073     * this server or all of the server if it's in a clustered environment have
074     * to follow.
075     */
076    Sentence byTag(String... names);
077
078    /**
079     * Executes the given action retrieving the socket tagged with the given
080     * name in this server or all of the server if it's in a clustered
081     * environment. The given action will be executed multiple times if sockets
082     * are found and won't be executed if not found.
083     */
084    Server byTag(String name, Action<Socket> action);
085
086    /**
087     * Executes the given action retrieving the socket tagged with all of the
088     * given names in this server or all of the server if it's in a clustered
089     * environment. The given action will be executed multiple times if sockets
090     * are found and won't be executed if not found.
091     */
092    Server byTag(String[] names, Action<Socket> action);
093
094    /**
095     * Registers an action to be called when the socket has been opened in this
096     * server regardless of clustering. It's allowed to add several actions
097     * before and after installation, so you don't need to centralize all your
098     * code to one class.
099     */
100    Server socketAction(Action<Socket> action);
101
102    /**
103     * ServerHttpExchange action to install in wes
104     */
105    Action<ServerHttpExchange> httpAction();
106
107    /**
108     * ServerWebSocket action to install in wes
109     */
110    Action<ServerWebSocket> websocketAction();
111
112}