org.objectweb.dream.protocol.channel.ChannelProtocol Maven / Gradle / Ivy

Go to download
/**
 * Dream
 * Copyright (C) 2003-2004 INRIA Rhone-Alpes
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 * Contact: [email protected]
 *
 * Initial developer(s): Matthieu Leclercq
 * Contributor(s): 
 */

package org.objectweb.dream.protocol.channel;

import java.util.Map;

import org.objectweb.dream.protocol.BindException;
import org.objectweb.dream.protocol.ExportException;
import org.objectweb.dream.protocol.ExportIdentifier;
import org.objectweb.dream.protocol.IPExportIdentifier;
import org.objectweb.dream.protocol.IncomingPush;
import org.objectweb.dream.protocol.InvalidExportIdentifierException;
import org.objectweb.dream.protocol.OutgoingPush;
import org.objectweb.dream.protocol.Protocol;

/**
 * A protocol is a naming context which can export {@link ChannelFactory}
 * interfaces.
 */
public interface ChannelProtocol extends Protocol {
    /**
     * This integer hint, used at bind time, can specify localaddr
     * and localport parameters of created socket. The associated
     * value MUST be an {@link IPExportIdentifier}.
     * 
     * @see #bind(ExportIdentifier, IncomingPush, Map)
     * @see java.net.Socket#Socket(String, int, java.net.InetAddress, int)
     */
    public static final String LOCAL_EXPORT_IDENTIFIER_KEY = "localExportIdentifier";

    /**
     * Exports a {@link ChannelFactory} interface using this protocol. This
     * method informs the protocol that the provided ChannelFactory
     * is willing to accept connection. The returned export identifier is a
     * specific name for the exported channel.
     * 
     * @param channel
     *      a ChannelFactory interface to export.
     * @param hints
     *      additional parameters, can be null.
     * @return an identifier for the exported interface.
     * @throws ExportException
     *      if the export process fails.
     */
    ExportIdentifier export(ChannelFactory channel, Map hints)
            throws ExportException;

    /**
     * Closes the export of a previously exported {@link ChannelFactory}
     * interface. This methods do not close communication channels created by
     * the exported channel factory.
     * 
     * @param exportIdentifier
     *      the export identifier of the channel.
     * @throws InvalidExportIdentifierException
     *      if the given export identifier is incorrect.
     */
    void unexport(ExportIdentifier exportIdentifier) throws InvalidExportIdentifierException;

    /**
     * Binds to a previously exported {@link ChannelFactory} interface
     * designated by the given export identifier. This methods instantiate a new
     * communication channel and returns an interface on which messages can be
     * sent to the server. In addition the toClientPush interface
     * is the interface on which the client want to receive messages from the
     * server.
     * 
     * @param exportId
     *      the identifier of the exported interface.
     * @param toClientPush
     *      the interface on which the client want to receive messages from the
     *      server, may be null if no messages are expected from
     *      the server.
     * @param hints
     *      additional parameters, can be null.
     * @return a OutgoingPush interface on which message can be
     *  send over the new communication channel.
     * @throws InvalidExportIdentifierException
     *      if the given export identifier is incorrect.
     * @throws BindException
     *      if the binding process fails.
     */
    OutgoingPush bind(ExportIdentifier exportId, IncomingPush toClientPush,
            Map hints) throws InvalidExportIdentifierException, BindException;

}