KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > excalibur > event > Source


1 /*
2  * Copyright 1999-2004 The Apache Software Foundation
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  * http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
12  * implied.
13  *
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 package org.apache.excalibur.event;
18
19 /**
20  * A Source implements the side of an event queue where QueueElements are
21  * dequeued operations only.
22  *
23  * <p>
24  * The interface design is heavily influenced by
25  * <a HREF="mailto:mdw@cs.berkeley.edu">Matt Welsh</a>'s SandStorm server,
26  * his demonstration of the SEDA architecture. We have deviated where we
27  * felt the design differences where better.
28  * </p>
29  *
30  * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
31  */
32 public interface Source
33 {
34     /**
35      * Sets the timeout on a blocking Source. Values above <code>1</code>
36      * will force all <code>dequeue</code> operations to block for up to that
37      * number of milliseconds waiting for new elements. Values below
38      * <code>1</code> will turn off blocking for Source. This is intentional
39      * because a Source should never block indefinitely.
40      *
41      * @param millis Number of milliseconds to block
42      */
43     void setTimeout( long millis );
44
45     /**
46      * Dequeues the next element, or <code>null</code> if there is
47      * nothing left on the queue or in case of a timeout while
48      * attempting to obtain the mutex
49      *
50      * @return the next queue element on the Source
51      */
52     Object JavaDoc dequeue();
53
54     /**
55      * Dequeues all available elements. Returns a zero-sized array in
56      * case of a timeout while attempting to obtain the mutex or if
57      * there is nothing left on the Source.
58      *
59      * @return all pending elements on the Source
60      */
61     Object JavaDoc[] dequeueAll();
62
63     /**
64      * Dequeues at most <code>num</code> available elements. Returns a
65      * zero-sized array in case of a timeout while attempting to
66      * obtain the mutex or if there is nothing left on the Source.
67      *
68      * @param num The maximum number of elements to dequeue
69      *
70      * @return At most <code>num</code> elements from the
71      * Source
72      */
73     Object JavaDoc[] dequeue( int num );
74
75     /**
76      * Returns the number of elements waiting in this Source.
77      *
78      * @return the number of elements in the Source
79      */
80     int size();
81 }
82
Popular Tags