/protocols/ss7/m3ua/api/src/main/java/org/mobicents/protocols/ss7/m3ua/M3UASelectionKey.java

  1/*
  2 * JBoss, Home of Professional Open Source
  3 * Copyright 2011, Red Hat, Inc. and individual contributors
  4 * by the @authors tag. See the copyright.txt in the distribution for a
  5 * full listing of individual contributors.
  6 *
  7 * This is free software; you can redistribute it and/or modify it
  8 * under the terms of the GNU Lesser General Public License as
  9 * published by the Free Software Foundation; either version 2.1 of
 10 * the License, or (at your option) any later version.
 11 *
 12 * This software is distributed in the hope that it will be useful,
 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 15 * Lesser General Public License for more details.
 16 *
 17 * You should have received a copy of the GNU Lesser General Public
 18 * License along with this software; if not, write to the Free
 19 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 20 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 21 */
 22
 23package org.mobicents.protocols.ss7.m3ua;
 24
 25/**
 26 * A token representing the registration of a M3UAChannel with a multiplexer.
 27 * 
 28 * A selection key is created each time a channel is registered with a selector.
 29 * A key remains valid until it is cancelled by invoking its cancel method, by
 30 * closing its channel, or by closing its selector. Cancelling a key does not
 31 * immediately remove it from its selector.
 32 * 
 33 * A selection key is created each time a channel is registered with a selector.
 34 * A key remains valid until it is cancelled by invoking its cancel method, by
 35 * closing its channel, or by closing its selector. Cancelling a key does not
 36 * immediately remove it from its selector
 37 * 
 38 * That a selection key's ready set indicates that its channel is ready for some
 39 * operation category is a hint, but not a guarantee, that an operation in such
 40 * a category may be performed by a thread without causing the thread to block.
 41 * A ready set is most likely to be accurate immediately after the completion of
 42 * a selection operation. It is likely to be made inaccurate by external events
 43 * and by I/O operations that are invoked upon the corresponding channel.
 44 * 
 45 * @author amit bhayani
 46 * @author kulikov
 47 */
 48public interface M3UASelectionKey {
 49    /**
 50     * Returns the channel for which this key was created. This method will
 51     * continue to return the channel even after the key is cancelled.
 52     * 
 53     * @return This key's channel.
 54     */
 55    public M3UASelectableChannel channel();
 56
 57    /**
 58     * Tests whether this key's channel is ready to accept a new connection.
 59     * 
 60     * @return true if, and only if channel ready to accept new connection
 61     */
 62    public boolean isAcceptable();
 63
 64    /**
 65     * Tests whether this key's channel is ready for reading.
 66     * 
 67     * @return true if, and only if channel ready for reading
 68     */
 69    public boolean isReadable();
 70
 71    /**
 72     * Tests whether this key's channel is ready for writting.
 73     * 
 74     * @return true if, and only if channel ready for writting
 75     */
 76    public boolean isWritable();
 77
 78    /**
 79     * Requests that the registration of this key's channel with its selector be
 80     * cancelled.
 81     */
 82    public void cancel();
 83
 84    /**
 85     * Attaches the given object to this key.
 86     * 
 87     * <p>
 88     * An attached object may later be retrieved via the {@link #attachment
 89     * attachment} method. Only one object may be attached at a time; invoking
 90     * this method causes any previous attachment to be discarded. The current
 91     * attachment may be discarded by attaching <tt>null</tt>.
 92     * </p>
 93     * 
 94     * @param ob
 95     *            The object to be attached; may be <tt>null</tt>
 96     * 
 97     * @return The previously-attached object, if any, otherwise <tt>null</tt>
 98     */
 99    public Object attach(Object ob);
100
101    /**
102     * Retrieves the current attachment.
103     * </p>
104     * 
105     * @return The object currently attached to this key, or <tt>null</tt> if
106     *         there is no attachment
107     */
108    public Object attachment();
109    
110    /**
111     * Tells whether or not this key is valid.
112     *
113     * <p> A key is valid upon creation and remains so until it is cancelled,
114     * its channel is closed, or its selector is closed.  </p>
115     *
116     * @return  <tt>true</tt> if, and only if, this key is valid
117     */
118    public abstract boolean isValid();
119
120}