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}