Source code: com/hp/hpl/jena/rdf/model/Model.java
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 */