001    /*
002     * Cumulus4j - Securing your data in the cloud - http://cumulus4j.org
003     * Copyright (C) 2011 NightLabs Consulting GmbH
004     *
005     * This program is free software: you can redistribute it and/or modify
006     * it under the terms of the GNU Affero General Public License as
007     * published by the Free Software Foundation, either version 3 of the
008     * License, or (at your option) any later version.
009     *
010     * This program is distributed in the hope that it will be useful,
011     * but WITHOUT ANY WARRANTY; without even the implied warranty of
012     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
013     * GNU Affero General Public License for more details.
014     *
015     * You should have received a copy of the GNU Affero General Public License
016     * along with this program.  If not, see <http://www.gnu.org/licenses/>.
017     */
018    package org.cumulus4j.keymanager.channel;
019    
020    import org.cumulus4j.keymanager.back.shared.ErrorResponse;
021    import org.cumulus4j.keymanager.back.shared.NullResponse;
022    import org.cumulus4j.keymanager.back.shared.Request;
023    import org.cumulus4j.keymanager.back.shared.Response;
024    
025    /**
026     * <p>
027     * Handler processing and replying requests coming from the application server.
028     * </p>
029     * <p>
030     * The so-called "key manager channel" is - as shown in the document
031     * <a target="_blank" href="http://cumulus4j.org/1.1.1/documentation/deployment-scenarios.html">Deployment scenarios</a> - an
032     * HTTP(S) connection from the key-manager to the application server with an inverse request-response-cycle.
033     * This means, the application server sends a {@link Request},
034     * the key manager handles it and then sends a {@link Response} back.
035     * </p>
036     * <p>
037     * For every {@link Request} type (i.e. subclass), there's one implementation of <code>RequestHandler</code>
038     * registered in the {@link KeyManagerChannelManager}. For every incoming <code>Request</code>, the
039     * <code>KeyManagerChannelManager</code> instantiates an appropriate <code>RequestHandler</code> implementation,
040     * initialises it (i.e. calls {@link #setKeyManagerChannelManager(KeyManagerChannelManager)}) and then calls
041     * {@link #handle(Request)}.
042     * </p>
043     * <p>
044     * If handling a request fails, an {@link ErrorResponse} is sent to the server.
045     * </p>
046     * <p>
047     * <b>Important:</b> You should not directly implement this interface but instead subclass {@link AbstractRequestHandler}!
048     * </p>
049     *
050     * @author Marco หงุ่ยตระกูล-Schulze - marco at nightlabs dot de
051     *
052     * @param <R> the request type for which this request handler is responsible.
053     */
054    public interface RequestHandler<R extends Request>
055    {
056            /**
057             * Get the {@link KeyManagerChannelManager}.
058             * @return the {@link KeyManagerChannelManager} or <code>null</code>, if it has not yet been set.
059             */
060            KeyManagerChannelManager getKeyManagerChannelManager();
061    
062            /**
063             * Set the {@link KeyManagerChannelManager}. This method is called by the <code>KeyManagerChannelManager</code>
064             * after instantiating a new <code>RequestHandler</code> instance and before invoking {@link #handle(Request)}.
065             * @param keyManagerChannelManager the {@link KeyManagerChannelManager}
066             */
067            void setKeyManagerChannelManager(KeyManagerChannelManager keyManagerChannelManager);
068    
069            /**
070             * Handle the given request.
071             * @param request the request to be handled; never <code>null</code>.
072             * @return the response for the given request; can be <code>null</code>, which is sent
073             * as {@link NullResponse} to the server.
074             */
075            Response handle(R request) throws Throwable;
076    }