View Javadoc

    1   /*
    2    *  Licensed to the Apache Software Foundation (ASF) under one
    3    *  or more contributor license agreements.  See the NOTICE file
    4    *  distributed with this work for additional information
    5    *  regarding copyright ownership.  The ASF licenses this file
    6    *  to you under the Apache License, Version 2.0 (the
    7    *  "License"); you may not use this file except in compliance
    8    *  with the License.  You may obtain a copy of the License at
    9    *
    10   *    http://www.apache.org/licenses/LICENSE-2.0
    11   *
    12   *  Unless required by applicable law or agreed to in writing,
    13   *  software distributed under the License is distributed on an
    14   *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    15   *  KIND, either express or implied.  See the License for the
    16   *  specific language governing permissions and limitations
    17   *  under the License.
    18   *
    19   */
    20  package org.apache.mina.core.service;
    21
    22  import java.util.Map;
    23  import java.util.Set;
    24
    25  import org.apache.mina.core.IoUtil;
    26  import org.apache.mina.core.filterchain.DefaultIoFilterChainBuilder;
    27  import org.apache.mina.core.filterchain.IoFilterChain;
    28  import org.apache.mina.core.filterchain.IoFilterChainBuilder;
    29  import org.apache.mina.core.future.WriteFuture;
    30  import org.apache.mina.core.session.IoSession;
    31  import org.apache.mina.core.session.IoSessionConfig;
    32  import org.apache.mina.core.session.IoSessionDataStructureFactory;
    33
    34  /**
    35   * Base interface for all {@link IoAcceptor}s and {@link IoConnector}s
    36   * that provide I/O service and manage {@link IoSession}s.
    37   *
    38   * @author <a href="http://mina.apache.org">Apache MINA Project</a>
    39   */
    40  public interface IoService {
    41      /**
    42       * Returns the {@link TransportMetadata} that this service runs on.
    43       */
    44      TransportMetadata getTransportMetadata();
    45
    46      /**
    47       * Adds an {@link IoServiceListener} that listens any events related with
    48       * this service.
    49       */
    50      void addListener(IoServiceListener listener);
    51
    52      /**
    53       * Removed an existing {@link IoServiceListener} that listens any events
    54       * related with this service.
    55       */
    56      void removeListener(IoServiceListener listener);
    57
    58      /**
    59       * Returns <tt>true</tt> if and if only {@link #dispose()} method has
    60       * been called.  Please note that this method will return <tt>true</tt>
    61       * even after all the related resources are released.
    62       */
    63      boolean isDisposing();
    64
    65      /**
    66       * Returns <tt>true</tt> if and if only all resources of this processor
    67       * have been disposed.
    68       */
    69      boolean isDisposed();
    70
    71      /**
    72       * Releases any resources allocated by this service.  Please note that
    73       * this method might block as long as there are any sessions managed by
    74       * this service.
    75       */
    76      void dispose();
    77
    78      /**
    79       * Releases any resources allocated by this service.  Please note that
    80       * this method might block as long as there are any sessions managed by this service.
    81       *
    82       * Warning : calling this method from a IoFutureListener with <code>awaitTermination</code> = true
    83       * will probably lead to a deadlock.
    84       *
    85       * @param awaitTermination When true this method will block until the underlying ExecutorService is terminated
    86       */
    87      void dispose(boolean awaitTermination);
    88
    89      /**
    90       * Returns the handler which will handle all connections managed by this service.
    91       */
    92      IoHandler getHandler();
    93
    94      /**
    95       * Sets the handler which will handle all connections managed by this service.
    96       */
    97      void setHandler(IoHandler handler);
    98
    99      /**
    100      * Returns the map of all sessions which are currently managed by this
    101      * service.  The key of map is the {@link IoSession#getId() ID} of the
    102      * session.
    103      *
    104      * @return the sessions. An empty collection if there's no session.
    105      */
    106     Map<Long, IoSession> getManagedSessions();
    107
    108     /**
    109      * Returns the number of all sessions which are currently managed by this
    110      * service.
    111      */
    112     int getManagedSessionCount();
    113
    114     /**
    115      * Returns the default configuration of the new {@link IoSession}s
    116      * created by this service.
    117      */
    118     IoSessionConfig getSessionConfig();
    119
    120     /**
    121      * Returns the {@link IoFilterChainBuilder} which will build the
    122      * {@link IoFilterChain} of all {@link IoSession}s which is created
    123      * by this service.
    124      * The default value is an empty {@link DefaultIoFilterChainBuilder}.
    125      */
    126     IoFilterChainBuilder getFilterChainBuilder();
    127
    128     /**
    129      * Sets the {@link IoFilterChainBuilder} which will build the
    130      * {@link IoFilterChain} of all {@link IoSession}s which is created
    131      * by this service.
    132      * If you specify <tt>null</tt> this property will be set to
    133      * an empty {@link DefaultIoFilterChainBuilder}.
    134      */
    135     void setFilterChainBuilder(IoFilterChainBuilder builder);
    136
    137     /**
    138      * A shortcut for <tt>( ( DefaultIoFilterChainBuilder ) </tt>{@link #getFilterChainBuilder()}<tt> )</tt>.
    139      * Please note that the returned object is not a <b>real</b> {@link IoFilterChain}
    140      * but a {@link DefaultIoFilterChainBuilder}.  Modifying the returned builder
    141      * won't affect the existing {@link IoSession}s at all, because
    142      * {@link IoFilterChainBuilder}s affect only newly created {@link IoSession}s.
    143      *
    144      * @throws IllegalStateException if the current {@link IoFilterChainBuilder} is
    145      *                               not a {@link DefaultIoFilterChainBuilder}
    146      */
    147     DefaultIoFilterChainBuilder getFilterChain();
    148
    149     /**
    150      * Returns a value of whether or not this service is active
    151      *
    152      * @return whether of not the service is active.
    153      */
    154     boolean isActive();
    155
    156     /**
    157      * Returns the time when this service was activated.  It returns the last
    158      * time when this service was activated if the service is not active now.
    159      *
    160      * @return The time by using {@link System#currentTimeMillis()}
    161      */
    162     long getActivationTime();
    163
    164     /**
    165      * Writes the specified {@code message} to all the {@link IoSession}s
    166      * managed by this service.  This method is a convenience shortcut for
    167      * {@link IoUtil#broadcast(Object, Collection)}.
    168      */
    169     Set<WriteFuture> broadcast(Object message);
    170
    171     /**
    172      * Returns the {@link IoSessionDataStructureFactory} that provides
    173      * related data structures for a new session created by this service.
    174      */
    175     IoSessionDataStructureFactory getSessionDataStructureFactory();
    176
    177     /**
    178      * Sets the {@link IoSessionDataStructureFactory} that provides
    179      * related data structures for a new session created by this service.
    180      */
    181     void setSessionDataStructureFactory(IoSessionDataStructureFactory sessionDataStructureFactory);
    182
    183     /**
    184      * Returns the number of bytes scheduled to be written
    185      *
    186      * @return The number of bytes scheduled to be written
    187      */
    188     int getScheduledWriteBytes();
    189
    190     /**
    191      * Returns the number of messages scheduled to be written
    192      *
    193      * @return The number of messages scheduled to be written
    194      */
    195     int getScheduledWriteMessages();
    196
    197     /**
    198      * Returns the IoServiceStatistics object for this service.
    199      *
    200      * @return The statistics object for this service.
    201      */
    202     IoServiceStatistics getStatistics();
    203 }