001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.wicket.protocol.ws.api.registry;
018
019import java.util.Collection;
020
021import org.apache.wicket.Application;
022import org.apache.wicket.protocol.ws.api.IWebSocketConnection;
023
024/**
025 * Tracks all currently connected WebSocket clients
026 *
027 * @since 6.0
028 */
029public interface IWebSocketConnectionRegistry
030{
031        /**
032         * Interface allowing to filter web-sockets connections. This could be used for use cases like the
033         * following: you need to deliver messages to all page instances satisfying certain conditions (e.g.
034         * they contain some progress reporting component).
035         */
036        interface IConnectionsFilter
037        {
038
039                boolean accept(String sessionId, IKey key);
040
041        }
042
043        /**
044         * @param application
045         *      the web application to look in
046         * @param sessionId
047         *      the http session id
048         * @param key
049         *      the web socket client key
050         * @return the web socket connection used by a client from the specified coordinates
051         */
052        IWebSocketConnection getConnection(Application application, String sessionId, IKey key);
053
054        /**
055         * @param application
056         *            the web application to look in
057         * @param sessionId
058         *            the http session id
059         * @return collection of web socket connections used by a client with the given session id
060         */
061        Collection<IWebSocketConnection> getConnections(Application application, String sessionId);
062
063
064        /**
065         *
066         * @param application
067         *                       the web application to look in
068         * @param connectionsFilter
069         *                      the {@link org.apache.wicket.protocol.ws.api.registry.IWebSocketConnectionRegistry.IConnectionsFilter}
070         *
071         * @return collection of web socket connections that match certain filter
072         */
073        Collection<IWebSocketConnection> getConnections(Application application, IConnectionsFilter connectionsFilter);
074
075
076        /**
077         * @param application
078         *            the web application to look in
079         * @return collection of web socket connection used by any client connected to specified application
080         */
081        Collection<IWebSocketConnection> getConnections(Application application);
082
083        /**
084         * Adds a new connection into the registry at the specified coordinates (application+session+page)
085         *
086         * @param application
087         *      the web application to look in
088         * @param sessionId
089         *      the http session id
090         * @param key
091         *      the web socket client key
092         * @param connection
093         *      the web socket connection to add
094         */
095        void setConnection(Application application, String sessionId, IKey key, IWebSocketConnection connection);
096
097        /**
098         * Removes a web socket connection from the registry at the specified coordinates (application+session+page)
099         *
100         * @param application
101         *      the web application to look in
102         * @param sessionId
103         *      the http session id
104         * @param key
105         *      the web socket client key
106         */
107        void removeConnection(Application application, String sessionId, IKey key);
108}