ViewVC Help

View File | Revision Log | Show Annotations | Download File | Root Listing

root/jsr166/jsr166/src/jsr166x/Deque.java

Comparing jsr166/src/jsr166x/Deque.java (file contents):
Revision 1.1 by dl, Sun Sep 5 21:28:19 2004 UTC vs.
Revision 1.6 by jsr166, Mon Nov 16 04:16:42 2009 UTC

#	Line 1 | Line 1
1		/*
2	<	* Written by Doug Lea with assistance from members of JCP JSR-166
3	<	* Expert Group and released to the public domain, as explained at
4	<	* http://creativecommons.org/licenses/publicdomain
2	>	* Written by Doug Lea and Josh Bloch with assistance from members of
3	>	* JCP JSR-166 Expert Group and released to the public domain, as explained
4	>	* at http://creativecommons.org/licenses/publicdomain
5		*/
6
7	<	package jsr166x;
8	<	import java.util.*;
7	>	package jsr166x;     // XXX This belongs in java.util!!! XXX
8	>	import java.util.*;    // XXX This import goes away        XXX
9
10		/**
11	<	* A linear collection in which elements may be inserted and removed
12	<	* from both the beginning and end. A <tt>Deque</tt> (short for
13	<	* "double ended queue") provides uniformly named methods to
14	<	* <tt>get</tt>, <tt>peek</tt>, <tt>poll</tt>, <tt>remove</tt>,
15	<	* <tt>offer</tt>, and <tt>add</tt> the <tt>first</tt> and
16	<	* <tt>last</tt> element of the collection (for example, methods
17	<	* <tt>addFirst</tt>, <tt>pollLast</tt>). Unlike interface {@link
18	<	* List} the Deque interface does not define support for indexed
19	<	* operations or sublists.
20	<	*
21	<	* <p>A view of a subset of Deque operations can be obtained using
22	<	* method {@link #asFIFO} to support only Last-In-First-Out (LIFO)
23	<	* stack behavior, as well as method {@link #asFIFO} to support only
24	<	* First-in-First-Out (FIFO) queue behavior.  More commonly, a Deque
25	<	* is used when various mixtures of LIFO and FIFO operations are
26	<	* required.
27	<	*
28	<	* <p>Deques additionally provide a few methods to manipulate elements
29	<	* embedded within a deque, proceding from either direction:
30	<	* <tt>removeFirstOccurrence</tt>, <tt>replaceFirstOccurrence</tt>
31	<	* <tt>removeLastOccurrence</tt>, and <tt>replaceLastOccurrence</tt>.
32	<	* They also support {@link Collection} operations including
33	<	* <tt>contains</tt>, <tt>iterator</tt>, and so on.
34	<	*
35	<	* <p>The {@link #offerFirst} and {@link #offerLast} methods insert an
36	<	* element if possible, otherwise returning <tt>false</tt>.  They
37	<	* differ from {@link java.util.Collection#add Collection.add}, as
38	<	* well as {@link #addFirst} and {@link #addLast} methods, which can
39	<	* fail to add an element only by throwing an unchecked exception.
40	<	* The <tt>offer</tt> methods are designed for use when failure is a
41	<	* normal, rather than exceptional occurrence, for example, in
42	<	* fixed-capacity (or &quot;bounded&quot;) deques.
43	<	*
44	<	* <p><tt>Deque</tt> implementations generally do not allow insertion
45	<	* of <tt>null</tt> elements.  Even in implementations that permit it,
46	<	* <tt>null</tt> should not be inserted into a <tt>Deque</tt>, as
47	<	* <tt>null</tt> is also used as a special return value by the poll
48	<	* methods to indicate that the deque contains no elements.
49	<	*
11	>	* A linear collection that supports element insertion and removal at
12	>	* both ends.  The name <i>deque</i> is short for "double ended queue"
13	>	* and is usually pronounced "deck".  Most <tt>Deque</tt>
14	>	* implementations place no fixed limits on the number of elements
15	>	* they may contain, but this interface supports capacity-restricted
16	>	* deques as well as those with no fixed size limit.
17	>	*
18	>	* <p>This interface defines methods to access the elements at both
19	>	* ends of the deque.  Methods are provided to insert, remove, and
20	>	* examine the element.  Each of these methods exists in two forms:
21	>	* one throws an exception if the operation fails, the other returns a
22	>	* special value (either <tt>null</tt> or <tt>false</tt>, depending on
23	>	* the operation).  The latter form of the insert operation is
24	>	* designed specifically for use with capacity-restricted
25	>	* <tt>Deque</tt> implementations; in most implementations, insert
26	>	* operations cannot fail.
27	>	*
28	>	* <p>The twelve methods described above are are summarized in the
29	>	* follwoing table:<p>
30	>	*
31	>	* <table BORDER CELLPADDING=3 CELLSPACING=1>
32	>	*  <tr>
33	>	*    <td></td>
34	>	*    <td ALIGN=CENTER COLSPAN = 2> <b>First Element (Head)</b></td>
35	>	*    <td ALIGN=CENTER COLSPAN = 2> <b>Last Element (Tail)</b></td>
36	>	*  </tr>
37	>	*  <tr>
38	>	*    <td></td>
39	>	*    <td ALIGN=CENTER><em>Throws exception</em></td>
40	>	*    <td ALIGN=CENTER><em>Returns special value</em></td>
41	>	*    <td ALIGN=CENTER><em>Throws exception</em></td>
42	>	*    <td ALIGN=CENTER><em>Returns special value</em></td>
43	>	*  </tr>
44	>	*  <tr>
45	>	*    <td><b>Insert</b></td>
46	>	*    <td>{@link #addFirst addFirst(e)}</td>
47	>	*    <td>{@link #offerFirst offerFirst(e)}</td>
48	>	*    <td>{@link #addLast addLast(e)}</td>
49	>	*    <td>{@link #offerLast offerLast(e)}</td>
50	>	*  </tr>
51	>	*  <tr>
52	>	*    <td><b>Remove</b></td>
53	>	*    <td>{@link #removeFirst removeFirst()}</td>
54	>	*    <td>{@link #pollFirst pollFirst()}</td>
55	>	*    <td>{@link #removeLast removeLast()}</td>
56	>	*    <td>{@link #pollLast pollLast()}</td>
57	>	*  </tr>
58	>	*  <tr>
59	>	*    <td><b>Examine</b></td>
60	>	*    <td>{@link #getFirst getFirst()}</td>
61	>	*    <td>{@link #peekFirst peekFirst()}</td>
62	>	*    <td>{@link #getLast getLast()}</td>
63	>	*    <td>{@link #peekLast peekLast()}</td>
64	>	*  </tr>
65	>	* </table>
66	>	*
67	>	* <p>This interface extends the {@link Queue} interface.  When a deque is
68	>	* used as a queue, FIFO (First-In-First-Out) behavior results.  Elements are
69	>	* added to the end of the deque and removed from the beginning.  The methods
70	>	* inherited from the <tt>Queue</tt> interface are precisely equivalent to
71	>	* <tt>Deque</tt> methods as indicated in the following table:<p>
72	>	*
73	>	* <table BORDER CELLPADDING=3 CELLSPACING=1>
74	>	*  <tr>
75	>	*    <td ALIGN=CENTER> <b><tt>Queue</tt> Method</b></td>
76	>	*    <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td>
77	>	*  </tr>
78	>	*  <tr>
79	>	*   <tr>
80	>	*    <td>{@link java.util.Queue#offer offer(e)}</td>
81	>	*    <td>{@link #offerLast offerLast(e)}</td>
82	>	*   </tr>
83	>	*   <tr>
84	>	*    <td>{@link java.util.Queue#add add(e)}</td>
85	>	*    <td>{@link #addLast addLast(e)}</td>
86	>	*   </tr>
87	>	*   <tr>
88	>	*    <td>{@link java.util.Queue#poll poll()}</td>
89	>	*    <td>{@link #pollFirst pollFirst()}</td>
90	>	*   </tr>
91	>	*   <tr>
92	>	*    <td>{@link java.util.Queue#remove remove()}</td>
93	>	*    <td>{@link #removeFirst removeFirst()}</td>
94	>	*   </tr>
95	>	*   <tr>
96	>	*    <td>{@link java.util.Queue#peek peek()}</td>
97	>	*    <td>{@link #peek peekFirst()}</td>
98	>	*   </tr>
99	>	*   <tr>
100	>	*    <td>{@link java.util.Queue#element element()}</td>
101	>	*    <td>{@link #getFirst getFirst()}</td>
102	>	*   </tr>
103	>	* </table>
104	>	*
105	>	* <p>Deques can also be used as LIFO (Last-In-First-Out) stacks.  This
106	>	* interface should be used in preference to the legacy {@link Stack} class.
107	>	* When a dequeue is used as a stack, elements are pushed and popped from the
108	>	* beginning of the deque.  Stack methods are precisely equivalent to
109	>	* <tt>Deque</tt> methods as indicated in the table below:<p>
110	>	*
111	>	* <table BORDER CELLPADDING=3 CELLSPACING=1>
112	>	*  <tr>
113	>	*    <td ALIGN=CENTER> <b>Stack Method</b></td>
114	>	*    <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td>
115	>	*  </tr>
116	>	*  <tr>
117	>	*   <tr>
118	>	*    <td>{@link #push push(e)}</td>
119	>	*    <td>{@link #addFirst addFirst(e)}</td>
120	>	*   </tr>
121	>	*   <tr>
122	>	*    <td>{@link #pop pop()}</td>
123	>	*    <td>{@link #removeFirst removeFirst()}</td>
124	>	*   </tr>
125	>	*   <tr>
126	>	*    <td>{@link #peek peek()}</td>
127	>	*    <td>{@link #peekFirst peekFirst()}</td>
128	>	*   </tr>
129	>	* </table>
130	>	*
131	>	* <p>Note that the {@link #peek peek} method works equally well when
132	>	* a deque is used as a queue or a stack; in either case, elements are
133	>	* drawn from the beginning of the deque.
134	>	*
135	>	* <p>This inteface provides two methods to to remove interior
136	>	* elements, {@link #removeFirstOccurrence removeFirstOccurrence} and
137	>	* {@link #removeLastOccurrence removeLastOccurrence}.  Unlike the
138	>	* {@link List} interface, this interface does not provide support for
139	>	* indexed access to elements.
140	>	*
141	>	* <p>While <tt>Deque</tt> implementations are not strictly required
142	>	* to prohibit the insertion of null elements, they are strongly
143	>	* encouraged to do so.  Users of any <tt>Deque</tt> implementations
144	>	* that do allow null elements are strongly encouraged <i>not</i> to
145	>	* take advantage of the ability to insert nulls.  This is so because
146	>	* <tt>null</tt> is used as a special return value by various methods
147	>	* to indicated that the deque is empty.
148	>	*
149		* <p><tt>Deque</tt> implementations generally do not define
150	<	* element-based versions of methods <tt>equals</tt> and
151	<	* <tt>hashCode</tt> but instead inherit the identity based versions
152	<	* from class <tt>Object</tt>.
150	>	* element-based versions of the <tt>equals</tt> and <tt>hashCode</tt>
151	>	* methods, but instead inherit the identity-based versions from class
152	>	* <tt>Object</tt>.
153		*
154		* <p>This interface is a member of the <a
155		* href="{@docRoot}/../guide/collections/index.html"> Java Collections
156		* Framework</a>.
157		*
158		* @author Doug Lea
159	+	* @author Josh Bloch
160	+	* @since  1.6
161		* @param <E> the type of elements held in this collection
162		*/
163	<	public interface Deque<E> extends Collection<E> {
63	<
163	>	public interface Deque<E> extends Queue<E> {
164		/**
165	<	* Inserts the specified element to the front this deque, if
166	<	* possible.  When using deques that may impose insertion
167	<	* restrictions (for example capacity bounds), method
168	<	* <tt>offerFirst</tt> is generally preferable to method
69	<	* <tt>addFirst</tt> which can fail to insert a non-duplicate
70	<	* element only by throwing an exception.
165	>	* Inserts the specified element to the front this deque unless it would
166	>	* violate capacity restrictions.  When using a capacity-restricted deque,
167	>	* this method is generally preferable to method <tt>addFirst</tt>, which
168	>	* can fail to insert an element only by throwing an exception.
169		*
170	<	* @param o the element to insert.
171	<	* @return <tt>true</tt> if it was possible to add the element to
172	<	* this deque, else <tt>false</tt>
170	>	* @param e the element to insert
171	>	* @return <tt>true</tt> if it was possible to insert the element,
172	>	*     else <tt>false</tt>
173	>	* @throws NullPointerException if <tt>e</tt> is null and this
174	>	*     deque does not permit null elements
175		*/
176	<	boolean offerFirst(E o);
176	>	boolean offerFirst(E e);
177
178		/**
179	<	* Inserts the specified element to the end this deque, if
180	<	* possible.  When using deques that may impose insertion
181	<	* restrictions (for example capacity bounds), method
182	<	* <tt>offerFirst</tt> is generally preferable to method
83	<	* <tt>addLast</tt> which can fail to insert a non-duplicate
84	<	* element only by throwing an exception.
179	>	* Inserts the specified element to the end of this deque unless it would
180	>	* violate capacity restrictions.  When using a capacity-restricted deque,
181	>	* this method is generally preferable to method <tt>addLast</tt> which
182	>	* can fail to insert an element only by throwing an exception.
183		*
184	<	* @param o the element to insert.
185	<	* @return <tt>true</tt> if it was possible to add the element to
186	<	* this deque, else <tt>false</tt>
184	>	* @param e the element to insert
185	>	* @return <tt>true</tt> if it was possible to insert the element,
186	>	*     else <tt>false</tt>
187	>	* @throws NullPointerException if <tt>e</tt> is null and this
188	>	*     deque does not permit null elements
189		*/
190	<	boolean offerLast(E o);
190	>	boolean offerLast(E e);
191
192		/**
193	<	* Inserts the specified element to the front this deque, if
194	<	* this deque permits insertion of the given element.  This
95	<	* method has the same semantics as {@link Collection#add}.
193	>	* Inserts the specified element to the front of this deque unless it
194	>	* would violate capacity restrictions.
195		*
196	<	* @param o the element to insert.
197	<	* @return <tt>true</tt> if this deque changed as a result of this
198	<	* call, else <tt>false</tt>
196	>	* @param e the element to insert
197	>	* @throws IllegalStateException if it was not possible to insert
198	>	*    the element due to capacity restrictions
199	>	* @throws NullPointerException if <tt>e</tt> is null and this
200	>	*     deque does not permit null elements
201		*/
202	<	boolean addFirst(E o);
202	>	void addFirst(E e);
203
204		/**
205	<	* Inserts the specified element to the end this deque, if
206	<	* this deque permits insertion of the given element.  This
106	<	* method has the same semantics as {@link Collection#add}.
205	>	* Inserts the specified element to the end of this deque unless it would
206	>	* violate capacity restrictions.
207		*
208	<	* @param o the element to insert.
209	<	* @return <tt>true</tt> if this deque changed as a result of this
210	<	* call, else <tt>false</tt>
208	>	* @param e the element to insert
209	>	* @throws IllegalStateException if it was not possible to insert
210	>	*    the element due to capacity restrictions
211	>	* @throws NullPointerException if <tt>e</tt> is null and this
212	>	*     deque does not permit null elements
213		*/
214	<	boolean addLast(E o);
214	>	void addLast(E e);
215
216		/**
217		* Retrieves and removes the first element of this deque, or
218		* <tt>null</tt> if this deque is empty.
219		*
220		* @return the first element of this deque, or <tt>null</tt> if
221	<	* this deque is empty.
221	>	*     this deque is empty
222		*/
223		E pollFirst();
224
#	Line 125 | Line 227 | public interface Deque<E> extends Collec
227		* <tt>null</tt> if this deque is empty.
228		*
229		* @return the last element of this deque, or <tt>null</tt> if
230	<	* this deque is empty.
230	>	*     this deque is empty
231		*/
232		E pollLast();
233
234		/**
235	<	* Retrieves and removes the first element of this deque.  This method
236	<	* differs from the <tt>pollFirst</tt> method in that it throws an
235	>	* Removes and returns the first element of this deque.  This method
236	>	* differs from the <tt>pollFirst</tt> method only in that it throws an
237		* exception if this deque is empty.
238		*
239	<	* @return the first element of this deque.
240	<	* @throws NoSuchElementException if this deque is empty.
239	>	* @return the first element of this deque
240	>	* @throws NoSuchElementException if this deque is empty
241		*/
242		E removeFirst();
243
244		/**
245		* Retrieves and removes the last element of this deque.  This method
246	<	* differs from the <tt>pollLast</tt> method in that it throws an
246	>	* differs from the <tt>pollLast</tt> method only in that it throws an
247		* exception if this deque is empty.
248		*
249	<	* @return the last element of this deque.
250	<	* @throws NoSuchElementException if this deque is empty.
249	>	* @return the last element of this deque
250	>	* @throws NoSuchElementException if this deque is empty
251		*/
252		E removeLast();
253
#	Line 154 | Line 256 | public interface Deque<E> extends Collec
256		* returning <tt>null</tt> if this deque is empty.
257		*
258		* @return the first element of this deque, or <tt>null</tt> if
259	<	* this deque is empty.
259	>	*     this deque is empty
260		*/
261		E peekFirst();
262
#	Line 163 | Line 265 | public interface Deque<E> extends Collec
265		* returning <tt>null</tt> if this deque is empty.
266		*
267		* @return the last element of this deque, or <tt>null</tt> if this deque
268	<	* is empty.
268	>	*     is empty
269		*/
270		E peekLast();
271
#	Line 172 | Line 274 | public interface Deque<E> extends Collec
274		* deque.  This method differs from the <tt>peek</tt> method only
275		* in that it throws an exception if this deque is empty.
276		*
277	<	* @return the first element of this deque.
278	<	* @throws NoSuchElementException if this deque is empty.
277	>	* @return the first element of this deque
278	>	* @throws NoSuchElementException if this deque is empty
279		*/
280		E getFirst();
281
#	Line 182 | Line 284 | public interface Deque<E> extends Collec
284		* deque.  This method differs from the <tt>peek</tt> method only
285		* in that it throws an exception if this deque is empty.
286		*
287	<	* @return the last element of this deque.
288	<	* @throws NoSuchElementException if this deque is empty.
287	>	* @return the last element of this deque
288	>	* @throws NoSuchElementException if this deque is empty
289		*/
290		E getLast();
291
#	Line 194 | Line 296 | public interface Deque<E> extends Collec
296		* such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
297		* such an element exists).
298		*
299	<	* @param o element to be removed from this deque, if present.
300	<	* @return <tt>true</tt> if the deque contained the specified element.
299	>	* @param e element to be removed from this deque, if present
300	>	* @return <tt>true</tt> if the deque contained the specified element
301		* @throws NullPointerException if the specified element is <tt>null</tt>
302		*/
303	<	boolean removeFirstOccurrence(E o);
303	>	boolean removeFirstOccurrence(Object e);
304
305		/**
306		* Removes the last occurrence of the specified element in this
#	Line 207 | Line 309 | public interface Deque<E> extends Collec
309		* such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
310		* such an element exists).
311		*
312	<	* @param o element to be removed from this deque, if present.
313	<	* @return <tt>true</tt> if the deque contained the specified element.
312	>	* @param e element to be removed from this deque, if present
313	>	* @return <tt>true</tt> if the deque contained the specified element
314		* @throws NullPointerException if the specified element is <tt>null</tt>
315		*/
316	<	boolean removeLastOccurrence(E o);
316	>	boolean removeLastOccurrence(Object e);
317	>
318	>
319	>	// *** Queue methods ***
320
321		/**
322	<	* Replaces the first occurrence of the specified element in this
323	<	* deque.  If the deque does not contain the element, it is
324	<	* unchanged.  More formally, replaces the first element <tt>e</tt>
325	<	* such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
326	<	* such an element exists).
322	>	* Inserts the specified element into the queue represented by this deque
323	>	* unless it would violate capacity restrictions.  In other words, inserts
324	>	* the specified element to the end of this deque.  When using a
325	>	* capacity-restricted deque, this method is generally preferable to the
326	>	* {@link #add} method, which can fail to insert an element only by
327	>	* throwing an exception.
328	>	*
329	>	* <p>This method is equivalent to {@link #offerLast}.
330		*
331	<	* @param oldElement element to be replaced in this deque, if present.
332	<	* @param newElement replacement value
333	<	* @return <tt>true</tt> if an element was replaced
331	>	* @param e the element to insert
332	>	* @return <tt>true</tt> if it was possible to insert the element,
333	>	*     else <tt>false</tt>
334	>	* @throws NullPointerException if <tt>e</tt> is null and this
335	>	*     deque does not permit null elements
336		*/
337	<	public boolean replaceFirstOccurrence(E oldElement, E newElement);
337	>	boolean offer(E e);
338
339		/**
340	<	* Replaces the last occurrence of the specified element in this
341	<	* deque.  If the deque does not contain the element, it is
342	<	* unchanged.  More formally, replaces the last element <tt>e</tt>
343	<	* such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
344	<	* such an element exists).
340	>	* Inserts the specified element into the queue represented by this
341	>	* deque unless it would violate capacity restrictions.  In other words,
342	>	* inserts the specified element as the last element of this deque.
343	>	*
344	>	* <p>This method is equivalent to {@link #addLast}.
345	>	*
346	>	* @param e the element to insert
347	>	* @return <tt>true</tt> (as per the spec for {@link Collection#add})
348	>	* @throws IllegalStateException if it was not possible to insert
349	>	*    the element due to capacity restrictions
350	>	* @throws NullPointerException if <tt>e</tt> is null and this
351	>	*     deque does not permit null elements
352	>	*/
353	>	boolean add(E e);
354	>
355	>	/**
356	>	* Retrieves and removes the head of the queue represented by
357	>	* this deque, or <tt>null</tt> if this deque is empty.  In other words,
358	>	* retrieves and removes the first element of this deque, or <tt>null</tt>
359	>	* if this deque is empty.
360	>	*
361	>	* <p>This method is equivalent to {@link #pollFirst()}.
362		*
363	<	* @param oldElement element to be replaced in this deque, if present.
364	<	* @param newElement replacement value
238	<	* @return <tt>true</tt> if an element was replaced
363	>	* @return the first element of this deque, or <tt>null</tt> if
364	>	*     this deque is empty
365		*/
366	<	public boolean replaceLastOccurrence(E oldElement, E newElement);
366	>	E poll();
367
368		/**
369	<	* Returns a view of this deque as a first-in-first-out queue,
370	<	* mapping {@link Queue#offer} to <tt>offerLast</tt>, {@link
371	<	* Queue#poll} to <tt>pollFirst</tt>, and other operations
372	<	* accordingly.
373	<	* @return a first-in-first-out view of this deque.
369	>	* Retrieves and removes the head of the queue represented by this deque.
370	>	* This method differs from the <tt>poll</tt> method only in that it
371	>	* throws an exception if this deque is empty.
372	>	*
373	>	* <p>This method is equivalent to {@link #removeFirst()}.
374	>	*
375	>	* @return the head of the queue represented by this deque
376	>	* @throws NoSuchElementException if this deque is empty
377	>	*/
378	>	E remove();
379	>
380	>	/**
381	>	* Retrieves, but does not remove, the head of the queue represented by
382	>	* this deque, returning <tt>null</tt> if this deque is empty.
383	>	*
384	>	* <p>This method is equivalent to {@link #peekFirst()}
385	>	*
386	>	* @return the head of the queue represented by this deque, or
387	>	*     <tt>null</tt> if this deque is empty
388		*/
389	<	public Queue<E> asFIFO();
389	>	E peek();
390
391		/**
392	<	* Returns a view of this deque as a first-in-Last-out stack,
393	<	* mapping {@link Queue#offer} to <tt>offerFirst</tt>, {@link
394	<	* Queue#poll} to <tt>pollFirst</tt>, and other operations
395	<	* accordingly.
396	<	* @return a first-in-last-out view of this deque.
392	>	* Retrieves, but does not remove, the head of the queue represented by
393	>	* this deque.  This method differs from the <tt>peek</tt> method only in
394	>	* that it throws an exception if this deque is empty.
395	>	*
396	>	* <p>This method is equivalent to {@link #getFirst()}
397	>	*
398	>	* @return the head of the queue represented by this deque
399	>	* @throws NoSuchElementException if this deque is empty
400		*/
401	<	public Queue<E> asLIFO();
401	>	E element();
402	>
403
404	+	// *** Stack methods ***
405	+
406	+	/**
407	+	* Pushes an element onto the stack represented by this deque.  In other
408	+	* words, inserts the element to the front this deque unless it would
409	+	* violate capacity restrictions.
410	+	*
411	+	* <p>This method is equivalent to {@link #addFirst}.
412	+	*
413	+	* @throws IllegalStateException if it was not possible to insert
414	+	*    the element due to capacity restrictions
415	+	* @throws NullPointerException if <tt>e</tt> is null and this
416	+	*     deque does not permit null elements
417	+	*/
418	+	void push(E e);
419	+
420	+	/**
421	+	* Pops an element from the stack represented by this deque.  In other
422	+	* words, removes and returns the the first element of this deque.
423	+	*
424	+	* <p>This method is equivalent to {@link #removeFirst()}.
425	+	*
426	+	* @return the element at the front of this deque (which is the top
427	+	*     of the stack represented by this deque)
428	+	* @throws NoSuchElementException if this deque is empty
429	+	*/
430	+	E pop();
431	+
432	+
433	+	// *** Collection Method ***
434	+
435	+	/**
436	+	* Returns an iterator over the elements in this deque.  The elements
437	+	* will be ordered from first (head) to last (tail).
438	+	*
439	+	* @return an <tt>Iterator</tt> over the elements in this deque
440	+	*/
441	+	Iterator<E> iterator();
442		}

Diff Legend

–	Removed lines
+	Added lines
<	Changed lines
>	Changed lines