KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > hp > hpl > jena > ontology > daml > DAMLList


1 /*****************************************************************************
2  * Source code information
3  * -----------------------
4  * Original author Ian Dickinson, HP Labs Bristol
5  * Author email Ian.Dickinson@hp.com
6  * Package Jena
7  * Created 4 Jan 2001
8  * Filename $RCSfile: DAMLList.java,v $
9  * Revision $Revision: 1.7 $
10  * Release status Preview-release $State: Exp $
11  *
12  * Last modified on $Date: 2005/02/21 12:05:00 $
13  * by $Author: andy_seaborne $
14  *
15  * (c) Copyright 2001, 2002, 2003, 2004, 2005 Hewlett-Packard Development Company, LP
16  * (see footer for full conditions)
17  *****************************************************************************/
18
19 // Package
20 ///////////////
21 package com.hp.hpl.jena.ontology.daml;
22
23
24 // Imports
25 ///////////////
26 import com.hp.hpl.jena.rdf.model.*;
27 import com.hp.hpl.jena.util.iterator.*;
28
29
30
31 /**
32  * <p>Java representation of a DAML List. A list is the specified interpretation of
33  * rdf:parseType="daml:Collection" attributes, where a sequence of values is
34  * interpreted as a nested sequence of head/tail list cells. One consequence of this
35  * is that the list is quite specifically ordered, whereas the daml:collection
36  * is said to be an unordered collection. Consquently, we must caution that future
37  * versions of the DAML specificiation may create an unordered interpretation of
38  * daml:collection, and client code should not rely on the positionality of elements
39  * in the current list interpretation.</p>
40  *
41  * @author Ian Dickinson, HP Labs (<a HREF="mailto:Ian.Dickinson@hp.com">email</a>)
42  * @version CVS info: $Id: DAMLList.java,v 1.7 2005/02/21 12:05:00 andy_seaborne Exp $
43  */
44 public interface DAMLList
45     extends RDFList
46 {
47     // Constants
48 //////////////////////////////////
49
50
51     // External signature methods
52 //////////////////////////////////
53
54
55     /**
56      * Answer an iteration over the values in the list.
57      *
58      * @return An iterator over the DAML values in the list
59      */
60     public ExtendedIterator getAll();
61
62
63     /**
64      * <p>Answer the value at the head of the list. Since, strictly speaking, DAML collections
65      * are unordered, the position items in the list should not be relied on in client
66      * code, as the definition of 'first' in the list may change in future releases.
67      * However, the identity
68      * <code><pre>
69      * List L = L.getFirst() + L.getRest()
70      * </pre></code>
71      * is guaranteed, providing that the contents of L do not change.
72      *
73      * @return The first value in the list.
74      */
75     public RDFNode getFirst();
76
77
78     /**
79      * <p>Answer a new list formed by creating a new DAMLList element whose first is the
80      * given value and whose rest is the current list. This is the 'cons' operator
81      * familiar from other list processing languages.</p>
82      *
83      * @param value The new value to be added to the head of the list
84      * @return a new list whose <code>daml:first</code> is the value, and whose
85      * <code>daml:rest</code> is this list.
86      */
87     public DAMLList cons( DAMLCommon value );
88
89
90     /**
91      * <p>Answer the list that consists of all values of the list save the first. Since, strictly
92      * speaking, DAML collections are unordered, this corresponds to returning the collection
93      * minus an unspecified one of its values. However, the identity
94      * <code><pre>
95      * List L = L.getFirst() + L.getRest()
96      * </pre></code>
97      * is guaranteed, providing that the contents of L do not change.</p>
98      *
99      * @return a list that contains all the elements of the current list, save the first one.
100      */
101     public DAMLList getRest();
102
103
104     /**
105      * <p>Answer a count of the items in the list. Does not check for duplications, so this
106      * is the count of entries in the list, not the count of distinct items in the list.</p>
107      *
108      * @return The number of entries in the list
109      */
110     public int getCount();
111
112
113
114     /**
115      * <p>Set the property <code>daml:first</code> for the given list element. This is a single
116      * value that denotes the value at this position of the list.</p>
117      *
118      * @param value The value to be assigned to the 'first' property of a list cell
119      */
120     public void setFirst( DAMLCommon value );
121
122
123     /**
124      * <p>Set the property <code>daml:rest</code> for the given list element. This is a single
125      * value that denotes the tail of the list.</p>
126      *
127      * @param tail The value to be assigned to the tail of the list.
128      */
129     public void setRest( DAMLList tail );
130
131
132     /**
133      * <p>Set the property <code>daml:rest</code> for the given list element to be the
134      * nil list. This correctly terminates the list at this point.</p>
135      */
136     public void setRestNil();
137
138
139     /**
140      * <p>Answer the well-known constant denoting the nil list.</p>
141      *
142      * @return The resource denoting nil
143      */
144     public DAMLList getNil();
145
146
147     /**
148      * <p>Answer true if the given resource is the nil list.</p>
149      *
150      * @param resource The resource to be tested
151      * @return true if the resource is the nil list
152      */
153     public boolean isNil( Resource resource );
154
155
156     /**
157      * <p>Find the last list element, i.e. the one whose rest is nil.</p>
158      *
159      * @return A list element
160      */
161     public DAMLList findLast();
162
163
164     /**
165      * <p>Answer the i'th element of the list, if it exists. If i is
166      * less than 1, or is larger than the length of the list, throw
167      * an illegal argument exception.</p>
168      *
169      * @param i The position of the list to return
170      * @return The DAML value at the i'th position in the list
171      * @exception ListIndexException if i is less than one, or
172      * larger than the length of the list.
173      */
174     public DAMLCommon getItem( int i );
175 }
176
177
178 /*
179     (c) Copyright 2001, 2002, 2003, 2004, 2005 Hewlett-Packard Development Company, LP
180     All rights reserved.
181
182     Redistribution and use in source and binary forms, with or without
183     modification, are permitted provided that the following conditions
184     are met:
185
186     1. Redistributions of source code must retain the above copyright
187        notice, this list of conditions and the following disclaimer.
188
189     2. Redistributions in binary form must reproduce the above copyright
190        notice, this list of conditions and the following disclaimer in the
191        documentation and/or other materials provided with the distribution.
192
193     3. The name of the author may not be used to endorse or promote products
194        derived from this software without specific prior written permission.
195
196     THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
197     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
198     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
199     IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
200     INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
201     NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
202     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
203     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
204     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
205     THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
206 */
207
208
Popular Tags