This project has retired. For details please refer to its Attic page.
Source code
001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.reef.io.network;
020
021import org.apache.reef.annotations.Unstable;
022import org.apache.reef.io.network.impl.NetworkConnectionServiceImpl;
023import org.apache.reef.tang.annotations.DefaultImplementation;
024import org.apache.reef.wake.EventHandler;
025import org.apache.reef.wake.Identifier;
026import org.apache.reef.wake.remote.Codec;
027import org.apache.reef.wake.remote.transport.LinkListener;
028
029/**
030 * NetworkConnectionService.
031 * <p>
032 * NetworkConnectionService is a service which is designed for communicating messages with each other.
033 * It creates multiple ConnectionFactories, which create multiple connections.
034 * <p>
035 * Flow of message transfer:
036 * <ul>
037 * <li>[Downstream]: {@code connection.write(message) -> ConnectionFactory
038 * -> src NetworkConnectionService (encode) -> dest NetworkConnectionService}.</li>
039 * <li>[Upstream]: {@code message -> dest NetworkConnectionService (decode) -> ConnectionFactory -> EventHandler}.</li>
040 * </ul>
041 * <p>
042 * Users can register a ConnectionFactory by registering their Codec, EventHandler, LinkListener and end point id.
043 * When users send messages via connections created by the ConnectionFactory,
044 * <p>
045 * NetworkConnectionService encodes the messages according to the Codec
046 * registered in the ConnectionFactory and sends them to the destination NetworkConnectionService.
047 * <p>
048 * Also, it receives the messages by decoding the messages and forwarding them
049 * to the corresponding EventHandler registered in the ConnectionFactory.
050 */
051@Unstable
052@DefaultImplementation(NetworkConnectionServiceImpl.class)
053public interface NetworkConnectionService extends AutoCloseable {
054
055  /**
056   * Registers an instance of ConnectionFactory corresponding to the connectionFactoryId.
057   * Binds Codec, EventHandler, LinkListener and localEndPointId to the ConnectionFactory.
058   * ConnectionFactory can create multiple connections between other NetworkConnectionServices.
059   * The connectionFactoryId is used to distinguish the type of connection and the localEndPointId
060   * is the contact point, which is registered to NameServer through this method.
061   *
062   * @param connectionFactoryId a connection factory id
063   * @param codec a codec for type T
064   * @param eventHandler an event handler for type T
065   * @param linkListener a link listener
066   * @param localEndPointId a local end point id
067   * @return the registered connection factory
068   */
069  <T> ConnectionFactory<T> registerConnectionFactory(final Identifier connectionFactoryId,
070                                     final Codec<T> codec,
071                                     final EventHandler<Message<T>> eventHandler,
072                                     final LinkListener<Message<T>> linkListener,
073                                     final Identifier localEndPointId);
074
075  /**
076   * Unregisters a connectionFactory corresponding to the connectionFactoryId
077   * and removes the localEndPointID of the connection factory from NameServer.
078   * @param connectionFactoryId a connection factory id
079   */
080  void unregisterConnectionFactory(final Identifier connectionFactoryId);
081
082  /**
083   * Gets an instance of ConnectionFactory which is registered by the registerConnectionFactory method.
084   *
085   * @param connectionFactoryId a connection factory id
086   */
087  <T> ConnectionFactory<T> getConnectionFactory(final Identifier connectionFactoryId);
088
089  /**
090   * Closes all resources and unregisters all registered connection factories.
091   *
092   * @throws Exception if this resource cannot be closed
093   */
094  void close() throws Exception;
095
096}