SimpleSelector


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  */
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags