Model


1   /*
2     (c) Copyright 2002, 2003, 2004, 2005 Hewlett-Packard Development Company, LP
3     [See end of file]
4     $Id: Model.java,v 1.59 2005/02/21 12:14:05 andy_seaborne Exp $
5   */
6   
7   package com.hp.hpl.jena.rdf.model;
8   
9   import com.hp.hpl.jena.datatypes.*;
10  import com.hp.hpl.jena.shared.*;
11  
12  import java.io.*;
13  import java.util.*;
14  
15  /** 
16      An RDF Model.
17  <p>    
18      An RDF model is a set of Statements.  Methods are provided for creating
19      resources, properties and literals and the Statements which link them,
20      for adding statements to and removing them from a model, for
21      querying a model and set operations for combining models.
22  <p>
23      Models may create Resources [URI nodes and bnodes]. Creating a Resource does
24      <i>not</i> make the Resource visible to the model; Resources are only "in" Models
25      if Statements about them are added to the Model. Similarly the only way to "remove"
26      a Resource from a Model is to remove all the Statements that mention it.
27  <p>
28      When a Resource or Literal is created by a Model, the Model is free to re-use an
29      existing Resource or Literal object with the correct values, or it may create a fresh
30      one. [All Jena RDFNodes and Statements are immutable, so this is generally safe.]
31  <p>    
32      This interface defines a set of primitive methods.  A set of
33      convenience methods which extends this interface, e.g. performing
34      automatic type conversions and support for enhanced resources,
35      is defined in {@link ModelCon}.</P>
36  
37   <h2>System Properties</h2>
38   
39   
40   <h3>Firewalls and Proxies</h3>
41   
42      Some of the methods, e.g. the read methods, may have to traverse a
43      firewall.  This can be accomplished using the standard java method
44      of setting system properties.  To use a socks proxy, include on the
45      java command line:</p>
46   * <blockquote>
47   *   -DsocksProxyHost=[your-proxy-domain-name-or-ip-address]
48   * </blockquote>
49   *
50   * <p>To use an http proxy, include on the command line:</p>
51   * <blockquote>
52   * -DproxySet=true -DproxyHost=[your-proxy] -DproxyPort=[your-proxy-port-number]
53   * </blockquote>
54   *
55   * <p>Alternatively, these properties can be set programatically, e.g.</p>
56   *
57   * <code><pre>
58   *   System.getProperties().put("proxySet","true");
59   *   System.getProperties().put("proxyHost","proxy.hostname");
60   *   System.getProperties().put("proxyPort",port_number);
61   * </pre></code>
62   *
63   * @author bwm
64   * @version $Name:  $ $Revision: 1.59 $Date: 2005/02/21 12:14:05 $'
65   */
66  public interface Model 
67      extends ModelCon, ModelGraphInterface, 
68          RDFReaderF, RDFWriterF, PrefixMapping, ModelLock
69  {
70  
71  
72      /** 
73       * size will return the number of statements in a concrete model, 
74       * for a virtualized model such as one created by an inference engine, 
75       * it will return an estimated lower bound for the numberof statements 
76       * in the model but it is possible for a subsequent listStatements on 
77       * such a model to discover more statements than size() indicated.
78       * @return the number of statements in a concrete model or an estimated
79       * lower bound on the number of statements in an virtualized model
80       */
81      long size() ;
82  
83      /**
84          Answer true iff the model contains no explicit statements (ie it's size is zero,
85          listStatements() would deliver the empty iterator).
86          
87          @return true iff the model contains no explicit statements.
88      */
89      boolean isEmpty();
90      
91      /** List all resources which are subjects of statements.
92       *
93       * <p>Subsequent operations on those resource may modify this model.</p>
94       
95       * @return an iterator over a set of resources which are subjects of statements
96       *         in the model. .remove() is not implemented on this iterator.
97       * 
98       */
99      ResIterator listSubjects() ;
100 
101     /** 
102         List the namespaces used by predicates and types in the model. This method is
103         really intended for use by the RDF/XML writer, which needs to know these
104         namespaces to generate correct and vaguely pretty XML.
105     <p>
106         The namespaces returned are those of (a) every URI used as a property in the
107         model and (b) those of every URI that appears as the object of an rdf:type statement.
108      
109        @return an iterator over every predicate and type namespace
110      */
111     NsIterator listNameSpaces() ;
112     
113     /** 
114         Return a Resource instance with the given URI in this model. <i>This method
115         behaves identically to <code>createResource(String)</code></i> and exists as
116         legacy: createResource is now capable of, and allowed to, reuse existing objects.
117     <p>
118         Subsequent operations on the returned object may modify this model.
119        @return a resource instance
120        @param uri the URI of the resource
121     */
122     Resource getResource(String   uri) ;
123 
124     /** 
125         Return a Property instance with the given URI in this model. <i>This method
126         behaves identically to <code>createProperty(String,String)</code></i> and exists as
127         legacy: createProperty is now capable of, and allowed to, reuse existing objects.
128     <p>
129         Subsequent operations on the returned property may modify this model.
130        @return a property linked to this model
131        @param nameSpace the RDF namespace of the property
132        @param localName the localName of the property in its namespace
133     */
134     Property getProperty(String   nameSpace, String   localName);
135 
136     /** 
137         Create a new anonymous resource whose model is this model. This bnode will 
138         have a new AnonId distinct from any allocated by any other call of this method.
139     <p> 
140         Subsequent operations on the returned resource may modify this model.
141        @return a new anonymous resource linked to this model.
142     */
143     public Resource createResource() ;
144 
145     /**
146         Create a blank node resource with a specified identifier. The resulting bnode
147         will be equal to any other bnode with the same AnonId (even if they are in
148         separate models - be warned). The intended use for this method is to allow
149         bnode round-tripping between Jena models and other representations.
150     <p>
151         This method may return an existing bnode with the correct AnonId and model, or it 
152         may construct a fresh one, as it sees fit.
153     <p>
154         Operations on the result may modify this model
155         @param id the identifier to use for this blank node
156         @return a blank node with that identifier
157     */
158     public Resource createResource( AnonId id );
159     
160     /** 
161         Create a new resource associated with this model. If the uri string is null, this creates
162         a bnode, as per <code>createResource()</code>. Otherwise it creates a URI node.
163         A URI resource is .equals() to any other URI Resource with the same URI (even in
164         a different model - be warned).
165     <p>
166         This method may return an existing Resource with the correct URI and model, or it 
167         may construct a fresh one, as it sees fit.
168     <p>
169         Operations on the result Resource may change this model.
170         
171        @param uri the URI of the resource to be created
172        @return a new resource linked to this model.
173     */
174     public Resource createResource( String   uri ) ;
175 
176     /** 
177         Create a property with a given URI composed from a namespace part and a
178         localname part by concatenating the strings.
179     <p>
180         This method may return an existing property with the correct URI and model, or it 
181         may construct a fresh one, as it sees fit.
182      <p> 
183         Subsequent operations on the returned property may modify this model.
184        @param nameSpace the nameSpace of the property
185        @param localName the name of the property within its namespace
186        @return a property instance
187     */
188     public Property createProperty(String   nameSpace, String   localName);
189 
190     /** 
191         Create an untyped literal from a String value with a specified language. 
192        @param v the lexical form of the literal
193        @param language the language associated with the literal
194        @return a new literal representing the value v with the given language
195      */
196 
197     public Literal createLiteral(String   v, String   language);
198 
199     /** 
200      * @deprecated since Jena2. It is no longer legal to have a language
201      * tag on a well-formed XMLLiteral. Use the 2-argument form of
202      * {@link #createLiteral(String, boolean) createLiteral} instead.
203      * 
204      *   Create a literal from a String value with a specified language. An existing literal
205      *   of the right value may be returned, or a fresh one created. 
206      *  @param v the lexical form of the literal
207      *  @param language the language associated with the literal
208      *  @param wellFormed true if the Literal is well formed XML
209      *  @return a new literal representing the value v with the given language
210      */
211     public Literal createLiteral(String   v, String   language, boolean wellFormed);
212 
213     /** 
214         Create a literal from a String value. An existing literal
215         of the right value may be returned, or a fresh one created. 
216         The use of the wellFormed flag is to create typed literals of
217         type rdf:XMLLiteral, without error checking. This should
218         only be use when the lexical form is known to already be
219         in exclusive canonical XML.
220         
221        @param v the lexical form of the literal
222        @param wellFormed true if the Literal is well formed XML, in the lexical space of rdf:XMLLiteral
223        @return a new literal 
224      */
225     public Literal createLiteral(String   v, boolean wellFormed);
226     
227     /**
228         Build a typed literal from its lexical form. The
229         lexical form will be parsed now and the value stored. If
230         the form is not legal this will throw an exception.
231         <p>
232         Note that in preview releases of Jena2 it was also possible to specify
233         a language type. Changes to the RDF specification mean that this is no longer
234         legal except for plain literals. To create a plain literal with a language tag
235         use {@link #createLiteral(String, String) createLiteral}. 
236         
237         @param lex the lexical form of the literal
238         @param dtype the type of the literal, null for old style "plain" literals
239         @throws DatatypeFormatException if lex is not a legal form of dtype
240      */
241     public Literal createTypedLiteral(String   lex, RDFDatatype dtype);
242     
243     /**
244      * Build a typed literal from its value form.
245      * <p>
246      * Note that in preview releases of Jena2 it was also possible to specify
247      *   a language type. Changes to the RDF specification mean that this is no longer
248      *   legal except for plain literals. To create a plain literal with a language tag
249      *   use {@link #createLiteral(String, String) createLiteral}. 
250      * </p> 
251      * @param value the value of the literal
252      * @param dtype the type of the literal, null for old style "plain" literals
253      */
254     public Literal createTypedLiteral(Object   value, RDFDatatype dtype);
255     
256     /**
257      * Build a typed literal label from its value form using
258      * whatever datatype is currently registered as the the default
259      * representation for this java class. No language tag is supplied.
260      * @param value the literal value to encapsulate
261      */
262     public Literal createTypedLiteral(Object   value);
263 
264     /** 
265        Create a Statement instance. (Creating a statement does not add it to the set of 
266        statements in the model; see Model::add). This method may return an existing 
267        Statement with the correct components and model, or it may construct a fresh one, 
268        as it sees fit.
269     <p>
270        Subsequent operations on the statement or any of its parts may modify this model.
271        @param s the subject of the statement
272        @param p the predicate of the statement
273        @param o the object of the statement
274        @return the new statement
275     */
276     public Statement createStatement( Resource s, Property p, RDFNode o );
277 
278     /**
279         Answer a new empty list. This is equivalent to a list consisting only 
280         of <code>rdf:nil</code>.
281         @return An RDF-encoded list of no elements
282     */
283     public RDFList createList();
284     
285     
286     /**
287      * <p>Answer a new list containing the resources from the given iterator, in order.</p>
288      * @param members An iterator, each value of which is expected to be an RDFNode
289      * @return An RDF-encoded list of the elements of the iterator
290      */
291     public RDFList createList( Iterator members );
292     
293     
294     /**
295      * <p>Answer a new list containing the nodes from the given array, in order</p>
296      * @param members An array of RDF nodes that will be the members of the list
297      * @return An RDF-encoded list 
298      */
299     public RDFList createList( RDFNode[] members );
300     
301     
302     /** Add a statement to this model.
303      * @return This model.
304      * @param s The statement to be added.
305      
306      */
307     Model add(Statement s) ;
308     
309     /**
310         Add all the statements to the Model, using through the bulk update interface.
311 
312         @param statements the array of statements to add
313         @return this model, to allow cascading
314     */    
315     Model add( Statement [] statements );
316     
317     /**
318         Remove all the statements from the Model, using the bulk update interface.
319         @param statements the array of statements to be added
320         @return this model, to allow cascading
321     */
322     Model remove( Statement [] statements );
323     
324     /**
325         add all the statements in the List to this Model, going through the bulk
326         update interface (which means turning them into triples in one form or
327         another).
328         @param statements a List of Statements
329         @return this model, to allow cascading
330     */    
331     Model add( List statements );
332     
333     /**
334         Remove all the statements in the list from this model, using the bulk
335         update interface.
336         @param statements a List of Statements to remove
337         @return this model, to allow cascading
338     */
339     Model remove( List statements );
340 
341     /** Add all the statements returned by an iterator to this model.
342      * @return this model
343      * @param iter An iterator which returns the statements to be added.
344      */
345     Model add(StmtIterator iter) ;
346 
347     /** Add all the statements in another model to this model, including the
348      * reified statements.
349      * @return this model
350      * @param m The model whose statements are to be added.
351      */
352     Model add(Model m) ;
353     
354     /**
355         Add all the statements of the given model m to this model.
356         Optionally supress the addition of reified statements.
357         @param m the model containing the statements to add
358         @param suppressReifications true to suppress adding reified statements
359         @return this model for cascading 
360     */
361     Model add( Model m, boolean suppressReifications );
362 
363     /** Add the RDF statements from an XML document.
364      *
365      * <p>See {@link Model} for a description of how to traverse a firewall.</p>
366      * @return this model
367      * @param url of the document containing the RDF statements.
368      
369      */
370     public Model read(String   url) ;
371 
372     /** Add statements from an RDF/XML serialization.
373      * @param in the source of the RDF/XML
374      * @param base the base to use when converting relative to absolute uri's.
375      * The base URI may be null if there are no relative URIs to convert.
376      * A base URI of "" may permit relative URIs to be used in the
377      * model unconverted.
378      * @return the current model
379      */
380     public Model read(InputStream in, String   base) ;
381 
382     /** Add RDF statements represented in language <code>lang</code> to the model.
383      * <br />Predefined values for <code>lang</code> are "RDF/XML", "N-TRIPLE"
384      * and "N3".  <code>null</code> represents the default language, "RDF/XML".
385      * "RDF/XML-ABBREV" is a synonym for "RDF/XML".
386      * <br />
387      *
388      * @return this model
389      * @param base the base uri to be used when converting relative
390      * URI's to absolute URI's.
391       The base URI may be null if there are no relative URIs to 
392       convert.
393       A base URI of "" may permit relative URIs to be used in the
394        model.
395      * @param lang the langauge of the serialization <code>null</code>
396      * selects the default
397      * @param in the source of the input serialization
398      */
399     public Model read(InputStream in, String   base, String   lang)
400         ;
401     
402     /** Using this method is often a mistake.
403      * Add statements from an RDF/XML serialization.
404      * It is generally better to use an InputStream if possible.
405      * {@link Model#read(InputStream,String)}, otherwise there is a danger of a
406      * mismatch between the character encoding of say the FileReader and the
407      * character encoding of the data in the file.
408      * @param reader the source of the RDF/XML
409      * @param base the base to use when converting relative to absolute uri's.
410       The base URI may be null if there are no relative URIs to 
411       convert.
412       A base URI of "" may permit relative URIs to be used in the
413        model.
414      * * @return the current model
415      */
416     public Model read(Reader reader, String   base) ;
417     
418     /** 
419      * Add statements from a serializion in language <code>lang</code> to the
420      * model.
421      * <br />Predefined values for <code>lang</code> are "RDF/XML", "N-TRIPLE"
422      * and "N3".  <code>null</code> represents the default language, "RDF/XML".
423      * "RDF/XML-ABBREV" is a synonym for "RDF/XML".
424      * <br />
425      *
426      * <p>See {@link Model} for a description of how to traverse a firewall.</p>
427      * @param url a string representation of the url to read from
428      * @param lang the language of the serialization
429      
430      * @return this model
431      */
432     public Model read(String   url, String   lang) ;
433 
434     /** Using this method is often a mistake.
435      * Add RDF statements represented in language <code>lang</code> to the model.
436      *<br />
437      *Predefined values for <code>lang</code> are "RDF/XML", "N-TRIPLE"
438      *and "N3".  <code>null</code> represents the default language, "RDF/XML".
439      *"RDF/XML-ABBREV" is a synonym for "RDF/XML".
440      * <br />
441      * It is generally better to use an InputStream if possible. 
442      * {@link Model#read(InputStream,String)}, otherwise there is a danger of a
443      * mismatch between the character encoding of say the FileReader and the
444      * character encoding of the data in the file.
445      * @return this model
446      * @param base the base uri to be used when converting relative
447      * URI's to absolute URI's.
448      
449       The base URI may be null if there are no relative URIs to 
450       convert.
451       A base URI of "" may permit relative URIs to be used in the
452        model.
453        
454      * @param lang the langauge of the serialization <code>null</code>
455      * selects the default
456      * @param reader the source of the input serialization
457      */
458     public Model read(Reader reader, String   base, String   lang);
459 
460     /**
461         Read into this model the RDF at <code>url</code>, using 
462         <code>baseURI</code> as the base URI if it is non-null. The RDF is assumed
463         to be RDF/XML unless <code>lang</code> is non-null, in which case it names
464         the language to be used. Answer this model.
465     */
466     Model read( String   url, String   base, String   lang );
467     
468     // output operations
469     
470     /** 
471      * <p>Write the model as an XML document.
472      * It is often better to use an OutputStream rather than a Writer, since this
473      * will avoid character encoding errors.  
474      * </p>
475      * 
476      * @param writer A writer to which the XML will be written
477      * @return this model
478      */
479     public Model write( Writer writer ) ;
480     
481     /** 
482      * <p>Write a serialized represention of a model in a specified language.
483      * It is often better to use an OutputStream rather than a Writer, since this
484      * will avoid character encoding errors.
485      * </p>
486      * <p>The language in which to write the model is specified by the
487      * <code>lang</code> argument.  Predefined values are "RDF/XML",
488      * "RDF/XML-ABBREV", "N-TRIPLE" and "N3".  The default value,
489      * represented by <code>null</code> is "RDF/XML".</p>
490      * @param writer The output writer
491      * @param lang The output language
492      * @return this model
493      */
494     public Model write( Writer writer, String   lang ) ;
495 
496     /** 
497      * <p>Write a serialized represention of a model in a specified language.
498      * It is often better to use an OutputStream rather than a Writer,
499      * since this will avoid character encoding errors.
500      * </p>
501      * <p>The language in which to write the model is specified by the
502      * <code>lang</code> argument.  Predefined values are "RDF/XML",
503      * "RDF/XML-ABBREV", "N-TRIPLE" and "N3".  The default value,
504      * represented by <code>null</code>, is "RDF/XML".</p>
505      * @param writer The output writer
506      * @param base The base uri for relative URI calculations.
507      * <code>null</code> means use only absolute URI's.
508      * @param lang The language in which the RDF should be written
509      * @return this model
510      */
511     public Model write( Writer writer, String   lang, String   base );
512     
513 
514     /** 
515      * <p>Write a serialization of this model as an XML document.
516      * </p>
517      * <p>The language in which to write the model is specified by the
518      * <code>lang</code> argument.  Predefined values are "RDF/XML",
519      * "RDF/XML-ABBREV", "N-TRIPLE" and "N3".  The default value is
520      * represented by <code>null</code> is "RDF/XML".</p>
521      * @param out The output stream to which the XML will be written
522      * @return This model
523      */
524     public Model write(OutputStream out) ;
525 
526     /** 
527      * <p>Write a serialized represention of this model in a specified language.
528      * </p>
529      * <p>The language in which to write the model is specified by the
530      * <code>lang</code> argument.  Predefined values are "RDF/XML",
531      * "RDF/XML-ABBREV", "N-TRIPLE" and "N3".  The default value,
532      * represented by <code>null</code>, is "RDF/XML".</p>
533      * @param out The output stream to which the RDF is written
534      * @param lang The output langauge
535      * @return This model
536      */
537     public Model write( OutputStream out, String   lang ) ;
538 
539     /** 
540      * <p>Write a serialized represention of a model in a specified language.
541      * </p>
542      * <p>The language in which to write the model is specified by the
543      * <code>lang</code> argument.  Predefined values are "RDF/XML",
544      * "RDF/XML-ABBREV", "N-TRIPLE" and "N3".  The default value,
545      * represented by <code>null</code>, is "RDF/XML".</p>
546      * @param out The output stream to which the RDF is written
547      * @param base The base uri to use when writing relative URI's. <code>null</code>
548      * means use only absolute URI's.
549      * @param lang The language in which the RDF should be written
550      * @return This model
551      */
552     public Model write( OutputStream out, String   lang, String   base );
553 
554     /** Removes a statement.
555      *
556      * <p> The statement with the same subject, predicate and object as
557      *     that supplied will be removed from the model.</p>
558      * @return this model
559      * @param s The statement to be removed.
560      
561      */
562     Model remove(Statement s) ;
563 
564     /** Return a statement with given subject and property.
565      *  <p>If more than one statement witht the given subject and property
566      *  exists in the model, it is undefined which will be returned. If none
567      * exist, an exception is thrown.
568      * @return A statement from the model with the given subject and property.
569      * @param s The subject of the statement to be returned.
570      * @param p The property of the statement to be returned.
571      * @throws PropertyNotFoundException
572      */
573     Statement getRequiredProperty(Resource s, Property p) ;
574     
575     /**
576         Answer a statement (s, p, ?O) from this model. If none exist, return null;
577         if several exist, pick one arbitrarily. 
578         @param s the subject of the statement to return
579         @param p the predicate of the statement to return
580         @return some statement (s, p, ?O) or null if none can be found
581     */
582     Statement getProperty( Resource s, Property p );
583 
584     /** List all subjects with a given property. .remove() is not implemented on
585      *  this iterator.
586      * @return an iterator over the subjects
587      * @param p the property sought.
588      
589      */
590     ResIterator listSubjectsWithProperty(Property p) ;
591 
592     /** List all subjects with a given property and property value.  .remove() is not
593      *  implemented on this iterator.
594      * @return an iterator over the subjects
595      * @param p The predicate sought
596      * @param o The value sought
597      */
598     ResIterator listSubjectsWithProperty(Property p, RDFNode o)
599         ;
600 
601     /** List all objects in a model.
602      * @return an iterator over the objects.  .remove() is not implemented on this iterator.
603      */
604     NodeIterator listObjects() ;
605 
606     /** List all objects of a given property.  .remove() is not implemented on this iterator.
607      * @return an iterator over the objects
608      * @param p The predicate sought
609      */
610     NodeIterator listObjectsOfProperty(Property p) ;
611 
612     /** List the values of a property of a resource.
613      * @return an iterator over the objects.  .remove() is not implemented on this iterator.
614      * @param p The predicate sought
615      */
616     NodeIterator listObjectsOfProperty(Resource s, Property p);
617 
618     /** Determine whether this model contains any statements with a given subject
619      *  and property.
620      * @return true if there exists within this model a statement with
621      * subject s and property p, false otherwise
622      * @param s The subject sought (null for any).
623      * @param p The predicate sought (null for any).
624      
625      */
626     boolean contains(Resource s, Property p) ;
627     
628     /**
629         determine if the RDFNode r appears in any statement of this model.
630         (containsRDFNode is a horrible name, and in any case, even literals
631         will be resources one day)
632         
633         @param r the RDFNode to be searched for
634         @return true iff r appears as some subject, predicate, or object
635     */
636     boolean containsResource( RDFNode r );
637 
638     /** Determine if an (S, P, O) pattern is present in this model, with null allowed
639      * to represent a wildcard match.
640      * @return true if the statement with subject s, property p and object o
641      * is in the model, false otherwise
642      * @param s The subject of the statment tested (null as wildcard).
643      * @param p The predicate of the statement tested (null as wildcard).
644      * @param o The object of the statement tested (null as wildcard).
645      
646      */
647     boolean contains(Resource s, Property p, RDFNode o) ;
648 
649     /** Determine if a statement is present in this model.
650      * @param s The statement tested.
651      
652      * @return true if the statement s is in this model, false otherwise
653     */
654     boolean contains(Statement s) ;
655 
656     /** Determine if any of the statements returned by an iterator are
657      * contained in this model.
658      * @param iter an iterator of the statements to be tested
659      
660      * @return true if any of the statements returns by iter are contained
661      *         in this model and false otherwise.
662     */
663     boolean containsAny(StmtIterator iter) ;
664 
665     /** Determine if all of the statements returned by an iterator are
666      * contained in this model.
667      * @param iter an iterator of the statements to be tested
668      
669      * @return true if any of the statements returns by iter are contained
670      *         in this model and false otherwise.
671     */
672     boolean containsAll(StmtIterator iter) ;
673 
674     /** Determine if any of the statements in a model are also contained
675      *  in this model.
676      * @param model the model containing the statements to be tested
677      
678      * @return true if any of the statements in model are also contained
679      *         in this model and false otherwise.
680     */
681     boolean containsAny(Model model) ;
682 
683     /** Determine if all of the statements in a model are also contained
684      *  in this model.
685      * @param model the model containing the statements to be tested
686      
687      * @return true if all of the statements in model are also contained
688      *         in this model and false otherwise.
689     */
690     boolean containsAll(Model model) ;
691 
692     /** 
693         Determine if this Statement has been reified in this Model.
694         
695        @param s The statement tested.
696        @return true iff a ReifiedStatement(s) has been created in this model
697     */
698     boolean isReified( Statement s );
699 
700     /**
701        Find or create a {@link ReifiedStatement} corresponding to a Statement.
702         @param s Statement which may or may not already be reified
703         @return a Resource [ReifiedStatement] that reifies the specified Statement.
704     */
705     Resource getAnyReifiedStatement( Statement s );
706 
707     /**
708         Remove all reifications (ie implicit reification quads) of _s_.
709     */
710     void removeAllReifications( Statement s );
711     
712     /**
713         Remove a particular reificiation.
714     */
715     void removeReification( ReifiedStatement rs );
716     
717     /** List all statements.
718      *
719      *  <p>Subsequent operations on those statements may modify this model.</p>
720      
721      * @return an iterator over all statements in the model.
722      */
723     StmtIterator listStatements() ;
724 
725     /** List the statements matching a selector.
726      *
727      * <p>A statment is considered to match if the <CODE>test</CODE> method
728      * of s returns true when called on s.</p>
729      * @return an iterator over the matching statements
730      * @param s A selector object.
731      .
732      */
733     StmtIterator listStatements(Selector s) ;
734     /** Find all the statements matching a pattern.
735      * <p>Return an iterator over all the statements in a model
736      *  that match a pattern.  The statements selected are those
737      *  whose subject matches the <code>subject</code> argument,
738      *  whose predicate matches the <code>predicate</code> argument
739      *  and whose object matches the <code>object</code> argument.
740      *  If an argument is <code>null</code> it matches anything.</p>
741      * @return an iterator over the subjects
742      * @param s   The subject sought
743      * @param p The predicate sought
744      * @param o    The value sought
745      */ 
746     
747     StmtIterator listStatements( Resource s, Property p, RDFNode o );
748     
749     /**
750         Answer a ReifiedStatement that encodes _s_ and belongs to this Model.
751     <br>
752         result.getModel() == this
753     <br>
754         result.getStatement() .equals ( s )
755     */
756     ReifiedStatement createReifiedStatement( Statement s );
757     
758     /**
759         answer a ReifiedStatement that encodes _s_, belongs to this Model,
760         and is a Resource with that _uri_.
761     */
762     ReifiedStatement createReifiedStatement( String   uri, Statement s );
763     
764     /**
765         answer an iterator delivering all the reified statements "in" this model
766     */
767     RSIterator listReifiedStatements();
768     
769     /**
770         answer an iterator delivering all the reified statements "in" this model
771         that match the statement _st_.
772     */
773     RSIterator listReifiedStatements( Statement st );
774     
775     /**
776         Answer the reification style of the model.
777         @return the reification style
778     */
779     ReificationStyle getReificationStyle();
780 
781     /** Create a new model containing the statements matching a query.
782      *
783      * <p>A statment is considered to match if the <CODE>test</CODE> method
784      * of s returns true when called on s.</p>
785      * @return an iterator over the matching statements
786      * @param s A selector object.
787      .
788      */
789     Model query(Selector s) ;
790 
791     /** Create a new model containing all the statements in this model 
792      * together with all of those in another given model.
793      * @return A new model containing all the statements that are in either model
794      * @param model The other model whose statements are to be included.
795      
796      */
797     Model union(Model model) ;
798 
799     /** Create a new model containing all the statements which are in both
800      * this model and another.  As models are sets of statements, a statement
801      * contained in both models will only appear once in the resulting model.
802      * @return A new model containing all the statements that are in both models.
803      * @param model The other model.
804      
805      */
806     Model intersection(Model model) ;
807 
808     /** Create a new model containing all the statements in this model which
809      * are not in another.
810      * @return a new model containing all the statements in this model that
811      *         are not in the given model.
812      * @param model the other model whose statements are to be excluded.
813      
814      */
815     Model difference(Model model) ;
816 
817     /** Test whether one model is the equal to another.
818      * Two Models  are equal iff the underlying graphs are identical Java
819      * objects.
820      * @param model the model to be compared
821      * @return true if the models are equal
822      */
823     public boolean equals(Object   model);
824 
825     /** Begin a new transation.
826      *
827      * <p> All changes made to a model within a transaction, will either
828      * be made, or none of them will be made.</p>
829      * @return this model to enable cascading.
830      
831      */
832     Model begin() ;
833 
834     /** Abort the current transaction and abandon any changes in progress.
835      * @return this model to enable cascading.
836      
837      */
838     Model abort() ;
839 
840     /** Commit the current transaction.
841      * @return this model to enable cascading.
842      
843      */
844     Model commit() ;
845     
846     /**
847         Execute the command <code>cmd</code> inside a transaction. If it
848         completes, commit the transaction and return the result; if it fails
849         (by throwing an exception), abort the transaction and throw an
850         exception.
851     */
852     Object   executeInTransaction( Command cmd );
853 
854     /** Determine whether this model is independent.
855      *
856      *  <p>For efficiency reasons, some implementations may create models which
857      *  which are dependent on others, i.e. a change in one model may cause
858      *  a change in another.  If this is the case this method will return false,
859      *  otherwise it will return true.</p>
860      *
861      * @return  true if this model is indepdent of others
862      */
863     boolean independent();
864 
865     /** Determine whether this model supports transactions.
866      * @return  true if this model supports transactions.
867      */
868     boolean supportsTransactions();
869 
870     /** Determine whether this model supports set operations.
871      * @return true if this model supports set operations.
872      */
873     boolean supportsSetOperations();
874     /**
875      * Compare this Model with another for equality ignoring the labels on
876      * bNodes.
877      * See
878      * <a HREF="http://www.w3.org/TR/rdf-concepts#section-Graph-syntax">RDF
879      * Concepts</a>.
880      * <p>Two models are isomorphic when each statement in one can be matched
881      * with a statement in the other.  Statements which are identical match.</p>
882      *
883      * <p>Special treatment is given to anonymous nodes.  A binding is a one to
884      * one mapping which maps each anonymous node in <code>this</code> model to
885      * an anonymous node in <code>model</code>.  Two statements s1 and s2 match
886      * under a binding if if s1.subject is anonymous and s2.subject is anonymous
887      * and the binding maps s1.subject to s2.subject.</p>
888      *
889      * <p>Two models are isomorphic if there is a binding that allows all the
890      * statements in one model to match a a statement in the other.</p>
891      * @param g Compare against this.
892      * @return boolean True if the two RDF graphs are isomorphic.
893      */
894     boolean isIsomorphicWith(Model g);
895 
896     /** Close the Model and free up resources held.
897      *
898      *  <p>Not all implementations of Model require this method to be called.  But
899      *     some do, so in general its best to call it when done with the object,
900      *     rather than leave it to the finalizer.</p>
901      */
902     public void close();
903     
904     /** Get the model lock for this model.
905      *  See also the convenience operations enterCriticalSection and leaveCriticalSection.
906      *  
907      * @see ModelLock
908      * @return The ModelLock object associated with this model 
909      */
910     public ModelLock getModelLock() ;
911     
912     /**
913         Register a listener for model-changed events on this model. The methods on
914         the listener will be called when API add/remove calls on the model succeed
915         [in whole or in part]. 
916     <p>
917         The same listener may be registered many times; if so, it's methods will
918         be called as many times as it's registered for each event.
919         
920         @see ModelChangedListener
921         @return this model, for cascading
922     */
923     public Model register( ModelChangedListener listener );
924     
925     /**
926         Unregister a listener from model-changed events on this model. The
927         listener is dtached from the model. The model is returned to permit
928         cascading. If the listener is not attached to the model, then nothing happens.
929         
930         @see ModelChangedListener
931         @return this model, for cascading
932     */
933     public Model unregister( ModelChangedListener listener );
934 
935     /**
936          Notify any listeners that the event e has occurred.
937         @param e the event that has occurred
938     */
939     public Model notifyEvent( Object   e );
940 
941     /**
942         Remove all the statements from this model.
943     */
944     public Model removeAll();
945 
946     /**
947         Remove all the statements matching (s, p, o) from this model.
948     */
949     public Model removeAll( Resource s, Property p, RDFNode r );
950     
951 }
952 
953 /*
954  *  (c)   Copyright 2000, 2001, 2002, 2003, 2004, 2005 Hewlett-Packard Development Company, LP
955  *   All rights reserved.
956  *
957  * Redistribution and use in source and binary forms, with or without
958  * modification, are permitted provided that the following conditions
959  * are met:
960  * 1. Redistributions of source code must retain the above copyright
961  *    notice, this list of conditions and the following disclaimer.
962  * 2. Redistributions in binary form must reproduce the above copyright
963  *    notice, this list of conditions and the following disclaimer in the
964  *    documentation and/or other materials provided with the distribution.
965  * 3. The name of the author may not be used to endorse or promote products
966  *    derived from this software without specific prior written permission.
967  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
968  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
969  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
970  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
971  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
972  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
973  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
974  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
975  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
976  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
977  *
978  * $Id: Model.java,v 1.59 2005/02/21 12:14:05 andy_seaborne Exp $
979  */
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags