001: /* Licensed to the Apache Software Foundation (ASF) under one or more
002: * contributor license agreements. See the NOTICE file distributed with
003: * this work for additional information regarding copyright ownership.
004: * The ASF licenses this file to You under the Apache License, Version 2.0
005: * (the "License"); you may not use this file except in compliance with
006: * the License. You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package java.nio.channels;
018:
019: import java.io.IOException;
020: import java.nio.channels.spi.SelectorProvider;
021: import java.util.Set;
022:
023: /**
024: * A controller for selection of SelectableChannel objects.
025: *
026: * Selectable channels can be registered with a selector, and get SelectionKey
027: * as a linkage. The keys are also added to the selector's keyset. The
028: * SelectionKey can be cancelled so that the corresponding channel is no longer
029: * registered with the selector.
030: *
031: * By invoking the select operation, the keyset is checked and all keys that are
032: * cancelled since last select operation are moved to cancelledKey set. During
033: * the select operation, the channels registered with this selector are checked
034: * to see whether they are ready for operation according to their interesting
035: * operation.
036: *
037: */
038: public abstract class Selector {
039:
040: /**
041: * The factory method for selector.
042: *
043: * @return a new selector
044: * @throws IOException
045: * if I/O error occurs
046: */
047: public static Selector open() throws IOException {
048: return SelectorProvider.provider().openSelector();
049: }
050:
051: /**
052: * The constructor.
053: */
054: protected Selector() {
055: super ();
056: }
057:
058: /**
059: * Closes this selector.
060: *
061: * @throws IOException
062: * if I/O error occurs
063: */
064: public abstract void close() throws IOException;
065:
066: /**
067: * Tells whether this selector is open.
068: *
069: * @return true if this selector is not closed
070: */
071: public abstract boolean isOpen();
072:
073: /**
074: * Gets the set of registered keys.
075: *
076: * @return the keyset of registered keys
077: */
078: public abstract Set<SelectionKey> keys();
079:
080: /**
081: * Gets the provider of this selector.
082: *
083: * @return the provider of this selector
084: */
085: public abstract SelectorProvider provider();
086:
087: /**
088: * Detects if any of the registered channels are ready for I/O operations
089: * according to their interesting operation. This operation will not return
090: * until some of the channels are ready or wakeup is invoked.
091: *
092: * @return the number of channels that are ready for operation
093: * @throws IOException
094: * if I/O error occurs
095: * @throws ClosedSelectorException
096: * If the selector is closed
097: */
098: public abstract int select() throws IOException;
099:
100: /**
101: * Detects if any of the registered channels are ready for I/O operations
102: * according to their interesting operation.This operation will not return
103: * until some of the channels are ready or wakeup is invoked or timeout
104: * expired.
105: *
106: * @param timeout
107: * the timeout in millisecond
108: * @return the number of channels that are ready for operation
109: * @throws IOException
110: * if I/O error occurs
111: * @throws ClosedSelectorException
112: * If the selector is closed
113: * @throws IllegalArgumentException
114: * If the given timeout argument is less than zero
115: */
116: public abstract int select(long timeout) throws IOException;
117:
118: /**
119: * Gets the keys whose channels are ready for operation.
120: *
121: * @return the keys whose channels are ready for operation
122: */
123: public abstract Set<SelectionKey> selectedKeys();
124:
125: /**
126: * Detects if any of the registered channels are ready for I/O operations
127: * according to their interesting operation.This operation will not return
128: * immediately.
129: *
130: * @return the number of channels that are ready for operation
131: * @throws IOException
132: * if I/O error occur
133: * @throws ClosedSelectorException
134: * If the selector is closed
135: */
136: public abstract int selectNow() throws IOException;
137:
138: /**
139: * Forces the blocked select operation to return immediately. If no select
140: * operation is blocked currently, the next select operation shall return
141: * immediately.
142: *
143: * @return this selector
144: * @throws ClosedSelectorException
145: * If the selector is closed
146: */
147: public abstract Selector wakeup();
148: }
|