Source code: com/hp/hpl/jena/rdf/model/SimpleSelector.java
1 /*
2 (c) Copyright 2003, 2004, 2005 Hewlett-Packard Development Company, LP
3 [See end of file]
4 $Id: SimpleSelector.java,v 1.13 2005/02/21 12:14:26 andy_seaborne Exp $
5 */
6
7 package com.hp.hpl.jena.rdf.model;
8
9 import com.hp.hpl.jena.rdf.model.impl.*;
10 import com.hp.hpl.jena.graph.*;
11
12 /**
13 A general selector class for use when querying models.
14
15 <p>An instance of this class is passed with query calls to models. The model
16 will use the <CODE>test</CODE> method of this class to decide whether
17 a statement should be included in the selection.
18
19 <p>Instances of this class can be provided with subject, predicate and object
20 constraints. If a subject, a predicate or an object are provided,
21 the model implementation <b>may</b> restrict the statements that it tests
22 to statements whose subject, predicate and object match those provided in
23 the constructor. This can provide for considerably more efficient
24 searching. However, the model implementation is not required to do this.
25 If no subject, predicate or object are provided in
26 the constructor, then all statements in the model must be tested.
27
28 <p>This class is designed to be subclassed by the application, defining
29 defining further selection criteria of its own by providing its own
30 <CODE>selects</CODE> method.
31
32 <p>A direct instance of SimpleSelector returns <code>true</code> for the
33 Selector::isSimple() predicate. Instances of subclasses of SimpleSelector
34 return <code>false</code>, since the only reason to have such subclasses
35 is to provide a non-trivial <code>test</code> predicate or S/P/O tests other
36 than equality.
37
38 <p>The <CODE>test</CODE> method first verifies that a statement satisfies
39 any subject, predicate or object constraints and the calls the <CODE>
40 selects</CODE> method to test for any application supplied constraint. The
41 default <CODE>selects</CODE> method simply returns true.
42
43 @author bwm
44 @version Release='$Name: $ $Revision: 1.13 $ $Date: 2005/02/21 12:14:26 $
45 */
46
47 public class SimpleSelector extends Object implements Selector {
48
49 protected Resource subject;
50 protected Property predicate;
51 protected RDFNode object;
52
53 /** Create a selector. Since no subject, predicate or object constraints are
54 * specified a model will test all statements.
55 */
56 public SimpleSelector() {
57 subject = null;
58 predicate = null;
59 object = null;
60 }
61
62 /** Create a selector. A model <b>may</b> restrict statements that are tested using
63 * the <CODE>selects</CODE> method to those whose subject matches the
64 * subject parameter, whose predicate matches the predicate parameter and whose
65 * object matches the object paramater. Any null parameter is considered to
66 * match anything.
67 * @param subject if not null, the subject of selected statements
68 * must equal this argument.
69 * @param predicate if not null, the predicate of selected statements
70 * must equal this argument.
71 * @param object if not null, the object of selected statements
72 * must equal this argument.
73 */
74 public SimpleSelector(Resource subject, Property predicate, RDFNode object) {
75 this.subject = subject;
76 this.predicate = predicate;
77 this.object = object;
78 }
79
80 /** Create a selector. A model <b>may</b> restrict statements that are tested using
81 * the <CODE>selects</CODE> method to those whose subject matches the
82 * subject parameter, whose predicate matches the predicate parameter and whose
83 * object matches the object paramater. Any null parameter is considered to
84 * match anything.
85 * @param subject if not null, the subject of selected statements
86 * must equal this argument.
87 * @param predicate if not null, the predicate of selected statements
88 * must equal this argument.
89 * @param object if not null, the object of selected statements
90 * must equal this argument.
91 */
92 public SimpleSelector(Resource subject, Property predicate, boolean object) {
93 this(subject, predicate, String.valueOf( object ) );
94 }
95
96 /** Create a selector. A model <b>may</b> restrict statements that are tested using
97 * the <CODE>selects</CODE> method to those whose subject matches the
98 * subject parameter, whose predicate matches the predicate parameter and whose
99 * object matches the object paramater. Any null parameter is considered to
100 * match anything.
101 * @param subject if not null, the subject of selected statements
102 * must equal this argument.
103 * @param predicate if not null, the predicate of selected statements
104 * must equal this argument.
105 * @param object the object of selected statements
106 * must equal this argument.
107 */
108 public SimpleSelector(Resource subject, Property predicate, long object) {
109 this(subject, predicate, String.valueOf( object ) );
110 }
111
112 /** Create a selector. A model <b>may</b> restrict statements that are tested using
113 * the <CODE>selects</CODE> method to those whose subject matches the
114 * subject parameter, whose predicate matches the predicate parameter and whose
115 * object matches the object paramater. Any null parameter is considered to
116 * match anything.
117 * @param subject if not null, the subject of selected statements
118 * must equal this argument.
119 * @param predicate if not null, the predicate of selected statements
120 * must equal this argument.
121 * @param object the object of selected statements
122 * must equal this argument.
123 */
124 public SimpleSelector(Resource subject, Property predicate, char object) {
125 this(subject, predicate, String.valueOf( object ) );
126 }
127
128 /** Create a selector. A model <b>may</b> restrict statements that are tested using
129 * the <CODE>selects</CODE> method to those whose subject matches the
130 * subject parameter, whose predicate matches the predicate parameter and whose
131 * object matches the object paramater. Any null parameter is considered to
132 * match anything.
133 * @param subject if not null, the subject of selected statements
134 * must equal this argument.
135 * @param predicate if not null, the predicate of selected statements
136 * must equal this argument.
137 * @param object the object of selected statements
138 * must equal this argument.
139 */
140 public SimpleSelector(Resource subject, Property predicate, float object) {
141 this(subject, predicate, String.valueOf( object ) );
142 }
143
144 /** Create a selector. A model <b>may</b> restrict statements that are tested using
145 * the <CODE>selects</CODE> method to those whose subject matches the
146 * subject parameter, whose predicate matches the predicate parameter and whose
147 * object matches the object paramater. Any null parameter is considered to
148 * match anything.
149 * @param subject if not null, the subject of selected statements
150 * must equal this argument.
151 * @param predicate if not null, the predicate of selected statements
152 * must equal this argument.
153 * @param object the object of selected statements
154 * must equal this argument.
155 */
156 public SimpleSelector(Resource subject, Property predicate, double object) {
157 this(subject, predicate, String.valueOf( object ) );
158 }
159
160 /** Create a selector. A model <b>may</b> restrict statements that are tested using
161 * the <CODE>selects</CODE> method to those whose subject matches the
162 * subject parameter, whose predicate matches the predicate parameter and whose
163 * object matches the object paramater. Any null parameter is considered to
164 * match anything.
165 * @param subject if not null, the subject of selected statements
166 * must equal this argument.
167 * @param predicate if not null, the predicate of selected statements
168 * must equal this argument.
169 * @param object the object of selected statements
170 * must equal this argument - a null string matches the empty string
171 */
172 public SimpleSelector(Resource subject, Property predicate, String object) {
173 this( subject, predicate, object, "" );
174 }
175
176 /** Create a selector. A model <b>may</b> restrict statements that are tested using
177 * the <CODE>selects</CODE> method to those whose subject matches the
178 * subject parameter, whose predicate matches the predicate parameter and whose
179 * object matches the object paramater. Any null parameter is considered to
180 * match anything.
181 * @param subject if not null, the subject of selected statements
182 * must equal this argument.
183 * @param predicate if not null, the predicate of selected statements
184 * must equal this argument.
185 * @param object the object of selected statements
186 * must equal this argument - the null string matches the empty string
187 * @param language the language of the object constraint
188 */
189 public SimpleSelector(Resource subject, Property predicate,
190 String object, String language) {
191 this.subject = subject;
192 this.predicate = predicate;
193 if (object != null) {
194 this.object = literal( object, language );
195 } else {
196 this.object = null;
197 }
198 }
199
200 private Literal literal( String s, String lang )
201 { return new LiteralImpl( Node.createLiteral( s, lang, false ), (ModelCom) null ); }
202
203 /** Create a selector. A model <b>may</b> restrict statements that are tested using
204 * the <CODE>selects</CODE> method to those whose subject matches the
205 * subject parameter, whose predicate matches the predicate parameter and whose
206 * object matches the object paramater. Any null parameter is considered to
207 * match anything.
208 * @param subject if not null, the subject of selected statements
209 * must equal this argument.
210 * @param predicate if not null, the predicate of selected statements
211 * must equal this argument.
212 * @param object if not null, the object of selected statements
213 * must equal this argument.
214 */
215 public SimpleSelector(Resource subject, Property predicate, Object object) {
216 this.subject = subject;
217 this.predicate = predicate;
218 if (object != null) {
219 this.object = literal( object.toString(), "" );
220 } else {
221 this.object = null;
222 }
223 }
224
225 /** Return the subject constraint of this selector.
226 * @return the subject constraint
227 */
228 public Resource getSubject() { return subject; }
229 /** Return the predicate constraint of this selector.
230 * @return the predicate constraint
231 */
232 public Property getPredicate() { return predicate; }
233 /** Return the object constraint of this selector.
234 * @return the object constraint
235 */
236 public RDFNode getObject() { return object; }
237
238 /**
239 Answer true iff this Selector is completely characterised by its
240 S/P/O triple. Subclasses will by default return false, so this method need not
241 be over-ridden (the only reason for subclassing SimpleSelector is to make
242 a test not dependent only on the S/P/O identity).
243
244 @return true iff this selector only depends on S/P/O identity.
245 */
246 public boolean isSimple()
247 { return this.getClass() == SimpleSelector.class; }
248
249 /** Test whether a statement should be included in a selection. This method
250 * tests whether the supplied statement satisfies the subject, predicate and
251 * object constraints of the selector and then tests whether it matches the
252 * application provided <CODE>selects</CODE> method.
253 * @param s the statement to be tested
254 * @return true if the statement satisfies the subject, object
255 * and predicate constraints and the selects constraint.
256 */
257 public boolean test(Statement s) {
258 return (subject == null || subject.equals(s.getSubject()))
259 && (predicate == null || predicate.equals(s.getPredicate()))
260 && (object == null || object.equals(s.getObject()))
261 && selects(s);
262 }
263
264 /** This method is designed to be over ridden by subclasses to define application
265 * specific constraints on the statements selected.
266 * @param s the statement to be tested
267 * @return true if the statement satisfies the constraint
268 */
269 public boolean selects(Statement s) {
270 return true;
271 }
272
273 }
274 /*
275 * (c) Copyright 2000 - 2002, 2003, 2004, 2005 Hewlett-Packard Development Company, LP
276 * All rights reserved.
277 *
278 * Redistribution and use in source and binary forms, with or without
279 * modification, are permitted provided that the following conditions
280 * are met:
281 * 1. Redistributions of source code must retain the above copyright
282 * notice, this list of conditions and the following disclaimer.
283 * 2. Redistributions in binary form must reproduce the above copyright
284 * notice, this list of conditions and the following disclaimer in the
285 * documentation and/or other materials provided with the distribution.
286 * 3. The name of the author may not be used to endorse or promote products
287 * derived from this software without specific prior written permission.
288
289 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
290 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
291 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
292 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
293 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
294 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
295 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
296 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
297 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
298 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
299 *
300 * SimpleSelector.java
301 *
302 * Created on 25 August 2000, 10:12
303 */