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}