01: /*
02: * Licensed to the Apache Software Foundation (ASF) under one or more
03: * contributor license agreements. See the NOTICE file distributed with
04: * this work for additional information regarding copyright ownership.
05: * The ASF licenses this file to You under the Apache License, Version 2.0
06: * (the "License"); you may not use this file except in compliance with
07: * the License. You may obtain a copy of the License at
08: *
09: * http://www.apache.org/licenses/LICENSE-2.0
10: *
11: * Unless required by applicable law or agreed to in writing, software
12: * distributed under the License is distributed on an "AS IS" BASIS,
13: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14: * See the License for the specific language governing permissions and
15: * limitations under the License.
16: */
17: package java.util;
18:
19: /**
20: * A kind of collection provides advanced operations than other basic
21: * collections, such as insertion, extraction, and inspection.
22: *
23: * Generally, a queue orders its elements by means of first-in-first-out. While
24: * priority queue orders its elements according to a comparator specified or the
25: * elements' natural order. Furthermore, a stack orders its elements
26: * last-in-first out.
27: *
28: * A typical queue does not allow null to be inserted as its element, while some
29: * implementations such as LinkedList allow it. But null should not be inserted
30: * even in these implementations, since method poll return null to indicate that
31: * there is no element left in the queue.
32: *
33: * Queue does not provide blocking queue methods, which will block until the
34: * operation of the method is allowed. BlockingQueue interface defines such
35: * methods.
36: */
37: public interface Queue<E> extends Collection<E> {
38:
39: /**
40: * Inserts the specified element into the queue provided that the condition
41: * allows such an operation. The method is generally preferable to the
42: * collection.add(E), since the latter might throw an exception if the
43: * operation fails.
44: *
45: * @param o
46: * the specified element to insert into the queue.
47: * @return true if the operation succeeds and false if it fails.
48: */
49: public boolean offer(E o);
50:
51: /**
52: * Gets and removes the element in the head of the queue, or returns null if
53: * there is no element in the queue.
54: *
55: * @return the element in the head of the queue or null if there is no
56: * element in the queue.
57: */
58: public E poll();
59:
60: /**
61: * Gets and removes the element in the head of the queue. Throws a
62: * NoSuchElementException if there is no element in the queue.
63: *
64: * @return the element in the head of the queue.
65: * @throws NoSuchElementException
66: * if there is no element in the queue.
67: */
68: public E remove();
69:
70: /**
71: * Gets but not removes the element in the head of the queue, or throws
72: * exception if there is no element in the queue.
73: *
74: * @return the element in the head of the queue or null if there is no
75: * element in the queue.
76: */
77: public E peek();
78:
79: /**
80: * Gets but not removes the element in the head of the queue. Throws a
81: * NoSuchElementException if there is no element in the queue.
82: *
83: * @return the element in the head of the queue.
84: * @throws NoSuchElementException
85: * if there is no element in the queue.
86: */
87: public E element();
88:
89: }
|