001/*
002 * This file is part of the JDrupes non-blocking HTTP Codec
003 * Copyright (C) 2016, 2017  Michael N. Lipp
004 *
005 * This program is free software; you can redistribute it and/or modify it 
006 * under the terms of the GNU Lesser General Public License as published
007 * by the Free Software Foundation; either version 3 of the License, or 
008 * (at your option) any later version.
009 *
010 * This program is distributed in the hope that it will be useful, but 
011 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
012 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 
013 * License for more details.
014 *
015 * You should have received a copy of the GNU Lesser General Public License along 
016 * with this program; if not, see <http://www.gnu.org/licenses/>.
017 */
018
019package org.jdrupes.httpcodec.plugin;
020
021import org.jdrupes.httpcodec.Decoder;
022import org.jdrupes.httpcodec.Encoder;
023import org.jdrupes.httpcodec.ProtocolException;
024import org.jdrupes.httpcodec.protocols.http.HttpRequest;
025import org.jdrupes.httpcodec.protocols.http.HttpResponse;
026
027/**
028 * The base class for a protocol that the HTTP connection
029 * can be upgraded to.
030 */
031public abstract class UpgradeProvider {
032
033        /**
034         * Checks if the plugin supports the given protocol.
035         * 
036         * @param protocol the protocol in question
037         * @return the result
038         */
039        public abstract boolean supportsProtocol(String protocol);
040
041        /**
042         * Add protocol specific information to a request with an `Upgrade`
043         * header field.
044         * 
045         * @param request the request
046         */
047        public abstract void augmentInitialRequest(HttpRequest request);
048
049        /**
050         * Check the `101 Switching Protocol` response for any problem
051         * indicators.
052         *
053         * @param request the request
054         * @param response the response
055         * @throws ProtocolException the protocol exception
056         */
057        public abstract void checkSwitchingResponse(
058                        HttpRequest request, HttpResponse response)
059                throws ProtocolException;
060        
061        /**
062         * Add any required information to the "switching protocols" response
063         * that is sent as the last package of the HTTP and starts the usage
064         * of the new protocol.
065         * 
066         * @param response the response
067         */
068        public abstract void augmentInitialResponse(HttpResponse response);
069        
070        /**
071         * Creates a new request encoder for the protocol.
072         * 
073         * @param protocol the protocol, which must be supported by this plugin
074         * @return the request encoder
075         */
076        public abstract Encoder<?, ?>   createRequestEncoder(String protocol);
077        
078        /**
079         * Creates a new request decoder for the protocol.
080         * 
081         * @param protocol the protocol, which must be supported by this plugin
082         * @return the request decoder
083         */
084        public abstract Decoder<?, ?> createRequestDecoder(String protocol);
085        
086        /**
087         * Creates a new response encoder for the protocol.
088         * 
089         * @param protocol the protocol, which must be supported by this plugin
090         * @return the response encoder
091         */
092        public abstract Encoder<?, ?> createResponseEncoder(String protocol);
093        
094        /**
095         * Creates a new response decoder for the protocol.
096         * 
097         * @param protocol the protocol, which must be supported by this plugin
098         * @return the response decoder
099         */
100        public abstract Decoder<?, ?> createResponseDecoder(String protocol);
101        
102        
103}