0001: /*
0002: (c) Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
0003: [See end of file]
0004: $Id: Model.java,v 1.71 2008/01/02 12:05:48 andy_seaborne Exp $
0005: */
0006:
0007: package com.hp.hpl.jena.rdf.model;
0008:
0009: import com.hp.hpl.jena.datatypes.*;
0010: import com.hp.hpl.jena.shared.*;
0011:
0012: import java.io.*;
0013: import java.util.*;
0014:
0015: /**
0016: An RDF Model.
0017: <p>
0018: An RDF model is a set of Statements. Methods are provided for creating
0019: resources, properties and literals and the Statements which link them,
0020: for adding statements to and removing them from a model, for
0021: querying a model and set operations for combining models.
0022: <p>
0023: Models may create Resources [URI nodes and bnodes]. Creating a Resource does
0024: <i>not</i> make the Resource visible to the model; Resources are only "in" Models
0025: if Statements about them are added to the Model. Similarly the only way to "remove"
0026: a Resource from a Model is to remove all the Statements that mention it.
0027: <p>
0028: When a Resource or Literal is created by a Model, the Model is free to re-use an
0029: existing Resource or Literal object with the correct values, or it may create a fresh
0030: one. [All Jena RDFNodes and Statements are immutable, so this is generally safe.]
0031: <p>
0032: This interface defines a set of primitive methods. A set of
0033: convenience methods which extends this interface, e.g. performing
0034: automatic type conversions and support for enhanced resources,
0035: is defined in {@link ModelCon}.</P>
0036:
0037: <h2>System Properties</h2>
0038:
0039:
0040: <h3>Firewalls and Proxies</h3>
0041:
0042: Some of the methods, e.g. the read methods, may have to traverse a
0043: firewall. This can be accomplished using the standard java method
0044: of setting system properties. To use a socks proxy, include on the
0045: java command line:</p>
0046: * <blockquote>
0047: * -DsocksProxyHost=[your-proxy-domain-name-or-ip-address]
0048: * </blockquote>
0049: *
0050: * <p>To use an http proxy, include on the command line:</p>
0051: * <blockquote>
0052: * -DproxySet=true -DproxyHost=[your-proxy] -DproxyPort=[your-proxy-port-number]
0053: * </blockquote>
0054: *
0055: * <p>Alternatively, these properties can be set programatically, e.g.</p>
0056: *
0057: * <code><pre>
0058: * System.getProperties().put("proxySet","true");
0059: * System.getProperties().put("proxyHost","proxy.hostname");
0060: * System.getProperties().put("proxyPort",port_number);
0061: * </pre></code>
0062: *
0063: * @author bwm
0064: * @version $Name: $ $Revision: 1.71 $Date: 2008/01/02 12:05:48 $'
0065: */
0066: public interface Model extends ModelCon, ModelGraphInterface,
0067: RDFReaderF, RDFWriterF, PrefixMapping, ModelLock {
0068:
0069: /**
0070: * size will return the number of statements in a concrete model,
0071: * for a virtualized model such as one created by an inference engine,
0072: * it will return an estimated lower bound for the numberof statements
0073: * in the model but it is possible for a subsequent listStatements on
0074: * such a model to discover more statements than size() indicated.
0075: * @return the number of statements in a concrete model or an estimated
0076: * lower bound on the number of statements in an virtualized model
0077: */
0078: long size();
0079:
0080: /**
0081: Answer true iff the model contains no explicit statements (ie it's size is zero,
0082: listStatements() would deliver the empty iterator).
0083:
0084: @return true iff the model contains no explicit statements.
0085: */
0086: boolean isEmpty();
0087:
0088: /** List all resources which are subjects of statements.
0089: *
0090: * <p>Subsequent operations on those resource may modify this model.</p>
0091:
0092: * @return an iterator over a set of resources which are subjects of statements
0093: * in the model. .remove() is not implemented on this iterator.
0094: *
0095: */
0096: ResIterator listSubjects();
0097:
0098: /**
0099: (You probably don't want this method; more likely you want the
0100: PrefixMapping methods that Model supports.) List the namespaces used
0101: by predicates and types in the model. This method is really intended
0102: for use by the RDF/XML writer, which needs to know these
0103: namespaces to generate correct and vaguely pretty XML.
0104: <p>
0105: The namespaces returned are those of (a) every URI used as a property in the
0106: model and (b) those of every URI that appears as the object of an rdf:type statement.
0107: <p>
0108: Note that the notion of "namespace" used here is not that of an XML
0109: prefix-namespace, but just of the minimal legal left part of a URI
0110: (see Util.splitNamespace for details). If you want the RDF/XML (or
0111: N3) namespaces, treat the Model as a PrefixMapping.
0112:
0113: @see com.hp.hpl.jena.shared.PrefixMapping
0114: @return an iterator over every predicate and type namespace
0115: */
0116: NsIterator listNameSpaces();
0117:
0118: /**
0119: Return a Resource instance with the given URI in this model. <i>This method
0120: behaves identically to <code>createResource(String)</code></i> and exists as
0121: legacy: createResource is now capable of, and allowed to, reuse existing objects.
0122: <p>
0123: Subsequent operations on the returned object may modify this model.
0124: @return a resource instance
0125: @param uri the URI of the resource
0126: */
0127: Resource getResource(String uri);
0128:
0129: /**
0130: Return a Property instance with the given URI in this model. <i>This method
0131: behaves identically to <code>createProperty(String,String)</code></i> and exists as
0132: legacy: createProperty is now capable of, and allowed to, reuse existing objects.
0133: <p>
0134: Subsequent operations on the returned property may modify this model.
0135: @return a property linked to this model
0136: @param nameSpace the RDF namespace of the property
0137: @param localName the localName of the property in its namespace
0138: */
0139: Property getProperty(String nameSpace, String localName);
0140:
0141: /**
0142: Create a new anonymous resource whose model is this model. This bnode will
0143: have a new AnonId distinct from any allocated by any other call of this method.
0144: <p>
0145: Subsequent operations on the returned resource may modify this model.
0146: @return a new anonymous resource linked to this model.
0147: */
0148: public Resource createResource();
0149:
0150: /**
0151: Create a blank node resource with a specified identifier. The resulting bnode
0152: will be equal to any other bnode with the same AnonId (even if they are in
0153: separate models - be warned). The intended use for this method is to allow
0154: bnode round-tripping between Jena models and other representations.
0155: <p>
0156: This method may return an existing bnode with the correct AnonId and model, or it
0157: may construct a fresh one, as it sees fit.
0158: <p>
0159: Operations on the result may modify this model
0160: @param id the identifier to use for this blank node
0161: @return a blank node with that identifier
0162: */
0163: public Resource createResource(AnonId id);
0164:
0165: /**
0166: Create a new resource associated with this model. If the uri string is null, this creates
0167: a bnode, as per <code>createResource()</code>. Otherwise it creates a URI node.
0168: A URI resource is .equals() to any other URI Resource with the same URI (even in
0169: a different model - be warned).
0170: <p>
0171: This method may return an existing Resource with the correct URI and model, or it
0172: may construct a fresh one, as it sees fit.
0173: <p>
0174: Operations on the result Resource may change this model.
0175:
0176: @param uri the URI of the resource to be created
0177: @return a new resource linked to this model.
0178: */
0179: public Resource createResource(String uri);
0180:
0181: /**
0182: Create a property with a given URI composed from a namespace part and a
0183: localname part by concatenating the strings.
0184: <p>
0185: This method may return an existing property with the correct URI and model, or it
0186: may construct a fresh one, as it sees fit.
0187: <p>
0188: Subsequent operations on the returned property may modify this model.
0189: @param nameSpace the nameSpace of the property
0190: @param localName the name of the property within its namespace
0191: @return a property instance
0192: */
0193: public Property createProperty(String nameSpace, String localName);
0194:
0195: /**
0196: Create an untyped literal from a String value with a specified language.
0197: @param v the lexical form of the literal
0198: @param language the language associated with the literal
0199: @return a new literal representing the value v with the given language
0200: */
0201:
0202: public Literal createLiteral(String v, String language);
0203:
0204: // /**
0205: // * @deprecated since Jena2. It is no longer legal to have a language
0206: // * tag on a well-formed XMLLiteral. Use the 2-argument form of
0207: // * {@link #createLiteral(String, boolean) createLiteral} instead.
0208: // *
0209: // * Create a literal from a String value with a specified language. An existing literal
0210: // * of the right value may be returned, or a fresh one created.
0211: // * @param v the lexical form of the literal
0212: // * @param language the language associated with the literal
0213: // * @param wellFormed true if the Literal is well formed XML
0214: // * @return a new literal representing the value v with the given language
0215: // */
0216: // public Literal createLiteral(String v, String language, boolean wellFormed);
0217:
0218: /**
0219: Create a literal from a String value. An existing literal
0220: of the right value may be returned, or a fresh one created.
0221: The use of the wellFormed flag is to create typed literals of
0222: type rdf:XMLLiteral, without error checking. This should
0223: only be use when the lexical form is known to already be
0224: in exclusive canonical XML.
0225:
0226: @param v the lexical form of the literal
0227: @param wellFormed true if the Literal is well formed XML, in the lexical space of rdf:XMLLiteral
0228: @return a new literal
0229: */
0230: public Literal createLiteral(String v, boolean wellFormed);
0231:
0232: /**
0233: Build a typed literal from its lexical form. The
0234: lexical form will be parsed now and the value stored. If
0235: the form is not legal this will throw an exception.
0236: <p>
0237: Note that in preview releases of Jena2 it was also possible to specify
0238: a language type. Changes to the RDF specification mean that this is no longer
0239: legal except for plain literals. To create a plain literal with a language tag
0240: use {@link #createLiteral(String, String) createLiteral}.
0241:
0242: @param lex the lexical form of the literal
0243: @param dtype the type of the literal, null for old style "plain" literals
0244: @throws DatatypeFormatException if lex is not a legal form of dtype
0245: */
0246: public Literal createTypedLiteral(String lex, RDFDatatype dtype);
0247:
0248: /**
0249: * Build a typed literal from its value form.
0250: * <p>
0251: * Note that in preview releases of Jena2 it was also possible to specify
0252: * a language type. Changes to the RDF specification mean that this is no longer
0253: * legal except for plain literals. To create a plain literal with a language tag
0254: * use {@link #createLiteral(String, String) createLiteral}.
0255: * </p>
0256: * @param value the value of the literal
0257: * @param dtype the type of the literal, null for old style "plain" literals
0258: */
0259: public Literal createTypedLiteral(Object value, RDFDatatype dtype);
0260:
0261: /**
0262: * Build a typed literal label from its value form using
0263: * whatever datatype is currently registered as the the default
0264: * representation for this java class. No language tag is supplied.
0265: * @param value the literal value to encapsulate
0266: */
0267: public Literal createTypedLiteral(Object value);
0268:
0269: /**
0270: Create a Statement instance. (Creating a statement does not add it to the set of
0271: statements in the model; see Model::add). This method may return an existing
0272: Statement with the correct components and model, or it may construct a fresh one,
0273: as it sees fit.
0274: <p>
0275: Subsequent operations on the statement or any of its parts may modify this model.
0276: @param s the subject of the statement
0277: @param p the predicate of the statement
0278: @param o the object of the statement
0279: @return the new statement
0280: */
0281: public Statement createStatement(Resource s, Property p, RDFNode o);
0282:
0283: /**
0284: Answer a new empty list. This is equivalent to a list consisting only
0285: of <code>rdf:nil</code>.
0286: @return An RDF-encoded list of no elements
0287: */
0288: public RDFList createList();
0289:
0290: /**
0291: * <p>Answer a new list containing the resources from the given iterator, in order.</p>
0292: * @param members An iterator, each value of which is expected to be an RDFNode
0293: * @return An RDF-encoded list of the elements of the iterator
0294: */
0295: public RDFList createList(Iterator members);
0296:
0297: /**
0298: * <p>Answer a new list containing the nodes from the given array, in order</p>
0299: * @param members An array of RDF nodes that will be the members of the list
0300: * @return An RDF-encoded list
0301: */
0302: public RDFList createList(RDFNode[] members);
0303:
0304: /** Add a statement to this model.
0305: * @return This model.
0306: * @param s The statement to be added.
0307:
0308: */
0309: Model add(Statement s);
0310:
0311: /**
0312: Add all the statements to the Model, using through the bulk update interface.
0313:
0314: @param statements the array of statements to add
0315: @return this model, to allow cascading
0316: */
0317: Model add(Statement[] statements);
0318:
0319: /**
0320: Remove all the statements from the Model, using the bulk update interface.
0321: @param statements the array of statements to be added
0322: @return this model, to allow cascading
0323: */
0324: Model remove(Statement[] statements);
0325:
0326: /**
0327: add all the statements in the List to this Model, going through the bulk
0328: update interface (which means turning them into triples in one form or
0329: another).
0330: @param statements a List of Statements
0331: @return this model, to allow cascading
0332: */
0333: Model add(List statements);
0334:
0335: /**
0336: Remove all the statements in the list from this model, using the bulk
0337: update interface.
0338: @param statements a List of Statements to remove
0339: @return this model, to allow cascading
0340: */
0341: Model remove(List statements);
0342:
0343: /** Add all the statements returned by an iterator to this model.
0344: * @return this model
0345: * @param iter An iterator which returns the statements to be added.
0346: */
0347: Model add(StmtIterator iter);
0348:
0349: /** Add all the statements in another model to this model, including the
0350: * reified statements.
0351: * @return this model
0352: * @param m The model whose statements are to be added.
0353: */
0354: Model add(Model m);
0355:
0356: /**
0357: Add all the statements of the given model m to this model.
0358: Optionally supress the addition of reified statements.
0359: @param m the model containing the statements to add
0360: @param suppressReifications true to suppress adding reified statements
0361: @return this model for cascading
0362: */
0363: Model add(Model m, boolean suppressReifications);
0364:
0365: /** Add the RDF statements from an XML document.
0366: * Uses content negotiation to request appropriate mime types.
0367: *
0368: * <p>See {@link Model} for a description of how to traverse a firewall.</p>
0369: * @return this model
0370: * @param url of the document containing the RDF statements.
0371:
0372: */
0373: public Model read(String url);
0374:
0375: /** Add statements from an RDF/XML serialization.
0376: * @param in the source of the RDF/XML
0377: * @param base the base to use when converting relative to absolute uri's.
0378: * The base URI may be null if there are no relative URIs to convert.
0379: * A base URI of "" may permit relative URIs to be used in the
0380: * model unconverted.
0381: * @return the current model
0382: */
0383: public Model read(InputStream in, String base);
0384:
0385: /** Add RDF statements represented in language <code>lang</code> to the model.
0386: * <br />Predefined values for <code>lang</code> are "RDF/XML", "N-TRIPLE"
0387: * and "N3". <code>null</code> represents the default language, "RDF/XML".
0388: * "RDF/XML-ABBREV" is a synonym for "RDF/XML".
0389: * <br />
0390: *
0391: * @return this model
0392: * @param base the base uri to be used when converting relative
0393: * URI's to absolute URI's.
0394: The base URI may be null if there are no relative URIs to
0395: convert.
0396: A base URI of "" may permit relative URIs to be used in the
0397: model.
0398: * @param lang the langauge of the serialization <code>null</code>
0399: * selects the default
0400: * @param in the source of the input serialization
0401: */
0402: public Model read(InputStream in, String base, String lang);
0403:
0404: /** Using this method is often a mistake.
0405: * Add statements from an RDF/XML serialization.
0406: * It is generally better to use an InputStream if possible.
0407: * {@link Model#read(InputStream,String)}, otherwise there is a danger of a
0408: * mismatch between the character encoding of say the FileReader and the
0409: * character encoding of the data in the file.
0410: * @param reader the source of the RDF/XML
0411: * @param base the base to use when converting relative to absolute uri's.
0412: The base URI may be null if there are no relative URIs to
0413: convert.
0414: A base URI of "" may permit relative URIs to be used in the
0415: model.
0416: * * @return the current model
0417: */
0418: public Model read(Reader reader, String base);
0419:
0420: /**
0421: * Add statements from a serializion in language <code>lang</code> to the
0422: * model.
0423: * <br />Predefined values for <code>lang</code> are "RDF/XML", "N-TRIPLE"
0424: * and "N3". <code>null</code> represents the default language, "RDF/XML".
0425: * "RDF/XML-ABBREV" is a synonym for "RDF/XML".
0426: * <br />
0427: *
0428: * <p>See {@link Model} for a description of how to traverse a firewall.</p>
0429: * @param url a string representation of the url to read from
0430: * @param lang the language of the serialization
0431:
0432: * @return this model
0433: */
0434: public Model read(String url, String lang);
0435:
0436: /** Using this method is often a mistake.
0437: * Add RDF statements represented in language <code>lang</code> to the model.
0438: *<br />
0439: *Predefined values for <code>lang</code> are "RDF/XML", "N-TRIPLE"
0440: *and "N3". <code>null</code> represents the default language, "RDF/XML".
0441: *"RDF/XML-ABBREV" is a synonym for "RDF/XML".
0442: * <br />
0443: * It is generally better to use an InputStream if possible.
0444: * {@link Model#read(InputStream,String)}, otherwise there is a danger of a
0445: * mismatch between the character encoding of say the FileReader and the
0446: * character encoding of the data in the file.
0447: * @return this model
0448: * @param base the base uri to be used when converting relative
0449: * URI's to absolute URI's.
0450:
0451: The base URI may be null if there are no relative URIs to
0452: convert.
0453: A base URI of "" may permit relative URIs to be used in the
0454: model.
0455:
0456: * @param lang the langauge of the serialization <code>null</code>
0457: * selects the default
0458: * @param reader the source of the input serialization
0459: */
0460: public Model read(Reader reader, String base, String lang);
0461:
0462: /**
0463: Read into this model the RDF at <code>url</code>, using
0464: <code>baseURI</code> as the base URI if it is non-null. The RDF is assumed
0465: to be RDF/XML unless <code>lang</code> is non-null, in which case it names
0466: the language to be used. Answer this model.
0467: */
0468: Model read(String url, String base, String lang);
0469:
0470: // output operations
0471:
0472: /**
0473: * <p>Write the model as an XML document.
0474: * It is often better to use an OutputStream rather than a Writer, since this
0475: * will avoid character encoding errors.
0476: * </p>
0477: *
0478: * @param writer A writer to which the XML will be written
0479: * @return this model
0480: */
0481: public Model write(Writer writer);
0482:
0483: /**
0484: * <p>Write a serialized represention of a model in a specified language.
0485: * It is often better to use an OutputStream rather than a Writer, since this
0486: * will avoid character encoding errors.
0487: * </p>
0488: * <p>The language in which to write the model is specified by the
0489: * <code>lang</code> argument. Predefined values are "RDF/XML",
0490: * "RDF/XML-ABBREV", "N-TRIPLE" and "N3". The default value,
0491: * represented by <code>null</code> is "RDF/XML".</p>
0492: * @param writer The output writer
0493: * @param lang The output language
0494: * @return this model
0495: */
0496: public Model write(Writer writer, String lang);
0497:
0498: /**
0499: * <p>Write a serialized represention of a model in a specified language.
0500: * It is often better to use an OutputStream rather than a Writer,
0501: * since this will avoid character encoding errors.
0502: * </p>
0503: * <p>The language in which to write the model is specified by the
0504: * <code>lang</code> argument. Predefined values are "RDF/XML",
0505: * "RDF/XML-ABBREV", "N-TRIPLE" and "N3". The default value,
0506: * represented by <code>null</code>, is "RDF/XML".</p>
0507: * @param writer The output writer
0508: * @param base The base uri for relative URI calculations.
0509: * <code>null</code> means use only absolute URI's.
0510: * @param lang The language in which the RDF should be written
0511: * @return this model
0512: */
0513: public Model write(Writer writer, String lang, String base);
0514:
0515: /**
0516: * <p>Write a serialization of this model as an XML document.
0517: * </p>
0518: * <p>The language in which to write the model is specified by the
0519: * <code>lang</code> argument. Predefined values are "RDF/XML",
0520: * "RDF/XML-ABBREV", "N-TRIPLE" and "N3". The default value is
0521: * represented by <code>null</code> is "RDF/XML".</p>
0522: * @param out The output stream to which the XML will be written
0523: * @return This model
0524: */
0525: public Model write(OutputStream out);
0526:
0527: /**
0528: * <p>Write a serialized represention of this model in a specified language.
0529: * </p>
0530: * <p>The language in which to write the model is specified by the
0531: * <code>lang</code> argument. Predefined values are "RDF/XML",
0532: * "RDF/XML-ABBREV", "N-TRIPLE" and "N3". The default value,
0533: * represented by <code>null</code>, is "RDF/XML".</p>
0534: * @param out The output stream to which the RDF is written
0535: * @param lang The output langauge
0536: * @return This model
0537: */
0538: public Model write(OutputStream out, String lang);
0539:
0540: /**
0541: * <p>Write a serialized represention of a model in a specified language.
0542: * </p>
0543: * <p>The language in which to write the model is specified by the
0544: * <code>lang</code> argument. Predefined values are "RDF/XML",
0545: * "RDF/XML-ABBREV", "N-TRIPLE" and "N3". The default value,
0546: * represented by <code>null</code>, is "RDF/XML".</p>
0547: * @param out The output stream to which the RDF is written
0548: * @param base The base uri to use when writing relative URI's. <code>null</code>
0549: * means use only absolute URI's. This is used for relative
0550: * URIs that would be resolved against the document retrieval URL.
0551: * For some values of <code>lang</code>, this value may be included in the output.
0552: * @param lang The language in which the RDF should be written
0553: * @return This model
0554: */
0555: public Model write(OutputStream out, String lang, String base);
0556:
0557: /** Removes a statement.
0558: *
0559: * <p> The statement with the same subject, predicate and object as
0560: * that supplied will be removed from the model.</p>
0561: * @return this model
0562: * @param s The statement to be removed.
0563:
0564: */
0565: Model remove(Statement s);
0566:
0567: /** Return a statement with given subject and property.
0568: * <p>If more than one statement witht the given subject and property
0569: * exists in the model, it is undefined which will be returned. If none
0570: * exist, an exception is thrown.
0571: * @return A statement from the model with the given subject and property.
0572: * @param s The subject of the statement to be returned.
0573: * @param p The property of the statement to be returned.
0574: * @throws PropertyNotFoundException
0575: */
0576: Statement getRequiredProperty(Resource s, Property p);
0577:
0578: /**
0579: Answer a statement (s, p, ?O) from this model. If none exist, return null;
0580: if several exist, pick one arbitrarily.
0581: @param s the subject of the statement to return
0582: @param p the predicate of the statement to return
0583: @return some statement (s, p, ?O) or null if none can be found
0584: */
0585: Statement getProperty(Resource s, Property p);
0586:
0587: /**
0588: An alias for <code>istResourcesWithProperty(Property)</code>,
0589: retained for backward compatability. It may be deprecated in later
0590: releases.
0591: */
0592: ResIterator listSubjectsWithProperty(Property p);
0593:
0594: /**
0595: Answer an iterator [with no duplicates] over all the resources in this
0596: model that have property <code>p</code>. <code>remove()</code>
0597: is not implemented on this iterator.
0598: */
0599: ResIterator listResourcesWithProperty(Property p);
0600:
0601: /**
0602: An alias for <code>listResourcesWithProperty</code>, retained for
0603: backward compatability. It may be deprecated in later releases.
0604: */
0605: ResIterator listSubjectsWithProperty(Property p, RDFNode o);
0606:
0607: /**
0608: Answer an iterator [with no duplicates] over all the resources in this
0609: model that have property <code>p</code> with value <code>o</code>.
0610: <code>remove()</code> is not implemented on this iterator.
0611: */
0612: ResIterator listResourcesWithProperty(Property p, RDFNode o);
0613:
0614: /** List all objects in a model.
0615: * @return an iterator over the objects. .remove() is not implemented on this iterator.
0616: */
0617: NodeIterator listObjects();
0618:
0619: /** List all objects of a given property. .remove() is not implemented on this iterator.
0620: * @return an iterator over the objects
0621: * @param p The predicate sought
0622: */
0623: NodeIterator listObjectsOfProperty(Property p);
0624:
0625: /** List the values of a property of a resource.
0626: * @return an iterator over the objects. .remove() is not implemented on this iterator.
0627: * @param p The predicate sought
0628: */
0629: NodeIterator listObjectsOfProperty(Resource s, Property p);
0630:
0631: /** Determine whether this model contains any statements with a given subject
0632: * and property.
0633: * @return true if there exists within this model a statement with
0634: * subject s and property p, false otherwise
0635: * @param s The subject sought (null for any).
0636: * @param p The predicate sought (null for any).
0637:
0638: */
0639: boolean contains(Resource s, Property p);
0640:
0641: /**
0642: determine if the RDFNode r appears in any statement of this model.
0643: (containsRDFNode is a horrible name, and in any case, even literals
0644: will be resources one day)
0645:
0646: @param r the RDFNode to be searched for
0647: @return true iff r appears as some subject, predicate, or object
0648: */
0649: boolean containsResource(RDFNode r);
0650:
0651: /** Determine if an (S, P, O) pattern is present in this model, with null allowed
0652: * to represent a wildcard match.
0653: * @return true if the statement with subject s, property p and object o
0654: * is in the model, false otherwise
0655: * @param s The subject of the statment tested (null as wildcard).
0656: * @param p The predicate of the statement tested (null as wildcard).
0657: * @param o The object of the statement tested (null as wildcard).
0658:
0659: */
0660: boolean contains(Resource s, Property p, RDFNode o);
0661:
0662: /** Determine if a statement is present in this model.
0663: * @param s The statement tested.
0664:
0665: * @return true if the statement s is in this model, false otherwise
0666: */
0667: boolean contains(Statement s);
0668:
0669: /** Determine if any of the statements returned by an iterator are
0670: * contained in this model.
0671: * @param iter an iterator of the statements to be tested
0672:
0673: * @return true if any of the statements returns by iter are contained
0674: * in this model and false otherwise.
0675: */
0676: boolean containsAny(StmtIterator iter);
0677:
0678: /** Determine if all of the statements returned by an iterator are
0679: * contained in this model.
0680: * @param iter an iterator of the statements to be tested
0681:
0682: * @return true if any of the statements returns by iter are contained
0683: * in this model and false otherwise.
0684: */
0685: boolean containsAll(StmtIterator iter);
0686:
0687: /** Determine if any of the statements in a model are also contained
0688: * in this model.
0689: * @param model the model containing the statements to be tested
0690:
0691: * @return true if any of the statements in model are also contained
0692: * in this model and false otherwise.
0693: */
0694: boolean containsAny(Model model);
0695:
0696: /** Determine if all of the statements in a model are also contained
0697: * in this model.
0698: * @param model the model containing the statements to be tested
0699:
0700: * @return true if all of the statements in model are also contained
0701: * in this model and false otherwise.
0702: */
0703: boolean containsAll(Model model);
0704:
0705: /**
0706: Determine if this Statement has been reified in this Model.
0707:
0708: @param s The statement tested.
0709: @return true iff a ReifiedStatement(s) has been created in this model
0710: */
0711: boolean isReified(Statement s);
0712:
0713: /**
0714: Find or create a {@link ReifiedStatement} corresponding to a Statement.
0715: @param s Statement which may or may not already be reified
0716: @return a Resource [ReifiedStatement] that reifies the specified Statement.
0717: */
0718: Resource getAnyReifiedStatement(Statement s);
0719:
0720: /**
0721: Remove all reifications (ie implicit reification quads) of _s_.
0722: */
0723: void removeAllReifications(Statement s);
0724:
0725: /**
0726: Remove a particular reificiation.
0727: */
0728: void removeReification(ReifiedStatement rs);
0729:
0730: /** List all statements.
0731: *
0732: * <p>Subsequent operations on those statements may modify this model.</p>
0733:
0734: * @return an iterator over all statements in the model.
0735: */
0736: StmtIterator listStatements();
0737:
0738: /** List the statements matching a selector.
0739: *
0740: * <p>A statment is considered to match if the <CODE>test</CODE> method
0741: * of s returns true when called on s.</p>
0742: * @return an iterator over the matching statements
0743: * @param s A selector object.
0744: .
0745: */
0746: StmtIterator listStatements(Selector s);
0747:
0748: /** Find all the statements matching a pattern.
0749: * <p>Return an iterator over all the statements in a model
0750: * that match a pattern. The statements selected are those
0751: * whose subject matches the <code>subject</code> argument,
0752: * whose predicate matches the <code>predicate</code> argument
0753: * and whose object matches the <code>object</code> argument.
0754: * If an argument is <code>null</code> it matches anything.</p>
0755: * @return an iterator over the subjects
0756: * @param s The subject sought
0757: * @param p The predicate sought
0758: * @param o The value sought
0759: */
0760:
0761: StmtIterator listStatements(Resource s, Property p, RDFNode o);
0762:
0763: /**
0764: Answer a ReifiedStatement that encodes _s_ and belongs to this Model.
0765: <br>
0766: result.getModel() == this
0767: <br>
0768: result.getStatement() .equals ( s )
0769: */
0770: ReifiedStatement createReifiedStatement(Statement s);
0771:
0772: /**
0773: answer a ReifiedStatement that encodes _s_, belongs to this Model,
0774: and is a Resource with that _uri_.
0775: */
0776: ReifiedStatement createReifiedStatement(String uri, Statement s);
0777:
0778: /**
0779: answer an iterator delivering all the reified statements "in" this model
0780: */
0781: RSIterator listReifiedStatements();
0782:
0783: /**
0784: answer an iterator delivering all the reified statements "in" this model
0785: that match the statement _st_.
0786: */
0787: RSIterator listReifiedStatements(Statement st);
0788:
0789: /**
0790: Answer the reification style of the model.
0791: @return the reification style
0792: */
0793: ReificationStyle getReificationStyle();
0794:
0795: /** Create a new model containing the statements matching a query.
0796: *
0797: * <p>A statment is considered to match if the <CODE>test</CODE> method
0798: * of s returns true when called on s.</p>
0799: * @return an iterator over the matching statements
0800: * @param s A selector object.
0801: .
0802: */
0803: Model query(Selector s);
0804:
0805: /**
0806: Create a new, independant, model containing all the statements in this model
0807: together with all of those in another given model. By <i>independant</i>
0808: we mean that changes to the result model do not affect the operand
0809: models, and <i>vice versa</i>.
0810: <p>
0811: The new model need not be of the same type as either this model or
0812: the argument model: typically it will be a memory-based model, even
0813: if this model is a database model.
0814:
0815: @return A new model containing all the statements that are in either model
0816: @param model The other model whose statements are to be included.
0817: */
0818: Model union(Model model);
0819:
0820: /**
0821: Create a new, independant, model containing all the statements which are in both
0822: this model and another. As models are sets of statements, a statement
0823: contained in both models will only appear once in the resulting model.
0824: The new model need not be of the same type as either this model or
0825: the argument model: typically it will be a memory-based model.
0826:
0827: @return A new model containing all the statements that are in both models.
0828: @param model The other model.
0829: */
0830: Model intersection(Model model);
0831:
0832: /** Create a new, independant, model containing all the statements in this model which
0833: * are not in another.
0834: The new model need not be of the same type as either this model or
0835: the argument model: typically it will be a memory-based model.
0836: * @return a new model containing all the statements in this model that
0837: * are not in the given model.
0838: * @param model the other model whose statements are to be excluded.
0839:
0840: */
0841: Model difference(Model model);
0842:
0843: /**
0844: * Test whether the given object <code>m</code>
0845: * is a model that is equal to this model,
0846: * which is true iff the underlying graphs are identical Java
0847: * objects. This is not the same test as comparing whether two models
0848: * have the same structure (i.e. contain the same set of statements).
0849: * To test for strucutural equivalence, see {@link #isIsomorphicWith}.
0850: * @param m the model to be compared
0851: * @return true if <code>m</code> shares a graph object with this model
0852: * @see #isIsomorphicWith(Model)
0853: */
0854: public boolean equals(Object m);
0855:
0856: /** Begin a new transation.
0857: *
0858: * <p> All changes made to a model within a transaction, will either
0859: * be made, or none of them will be made.</p>
0860: * @return this model to enable cascading.
0861:
0862: */
0863: Model begin();
0864:
0865: /** Abort the current transaction and abandon any changes in progress.
0866: * @return this model to enable cascading.
0867:
0868: */
0869: Model abort();
0870:
0871: /** Commit the current transaction.
0872: * @return this model to enable cascading.
0873:
0874: */
0875: Model commit();
0876:
0877: /**
0878: Execute the command <code>cmd</code> inside a transaction. If it
0879: completes, commit the transaction and return the result; if it fails
0880: (by throwing an exception), abort the transaction and throw an
0881: exception.
0882: */
0883: Object executeInTransaction(Command cmd);
0884:
0885: /** Determine whether this model is independent.
0886: *
0887: * <p>For efficiency reasons, some implementations may create models which
0888: * which are dependent on others, i.e. a change in one model may cause
0889: * a change in another. If this is the case this method will return false,
0890: * otherwise it will return true.</p>
0891: *
0892: * @return true if this model is indepdent of others
0893: */
0894: boolean independent();
0895:
0896: /** Determine whether this model supports transactions.
0897: * @return true if this model supports transactions.
0898: */
0899: boolean supportsTransactions();
0900:
0901: /** Determine whether this model supports set operations.
0902: * @return true if this model supports set operations.
0903: */
0904: boolean supportsSetOperations();
0905:
0906: /**
0907: * Compare this Model with another for equality ignoring the labels on
0908: * bNodes.
0909: * See
0910: * <a href="http://www.w3.org/TR/rdf-concepts#section-Graph-syntax">RDF
0911: * Concepts</a>.
0912: * <p>Two models are isomorphic when each statement in one can be matched
0913: * with a statement in the other. Statements which are identical match.</p>
0914: *
0915: * <p>Special treatment is given to anonymous nodes. A binding is a one to
0916: * one mapping which maps each anonymous node in <code>this</code> model to
0917: * an anonymous node in <code>model</code>. Two statements s1 and s2 match
0918: * under a binding if if s1.subject is anonymous and s2.subject is anonymous
0919: * and the binding maps s1.subject to s2.subject.</p>
0920: *
0921: * <p>Two models are isomorphic if there is a binding that allows all the
0922: * statements in one model to match a a statement in the other.</p>
0923: * @param g Compare against this.
0924: * @return boolean True if the two RDF graphs are isomorphic.
0925: */
0926: boolean isIsomorphicWith(Model g);
0927:
0928: /** Close the Model and free up resources held.
0929: *
0930: * <p>Not all implementations of Model require this method to be called. But
0931: * some do, so in general its best to call it when done with the object,
0932: * rather than leave it to the finalizer.</p>
0933: */
0934: public void close();
0935:
0936: // /** Get the model lock for this model.
0937: // * See also the convenience operations enterCriticalSection and leaveCriticalSection.
0938: // *
0939: // * @see ModelLock
0940: // * @return The ModelLock object associated with this model
0941: // * @deprecated Applications should use {@link #getLock()}
0942: // */
0943: // public ModelLock getModelLock() ;
0944:
0945: /** Get the model lock for this model.
0946: * See also the convenience operations enterCriticalSection and leaveCriticalSection.
0947: *
0948: * @see ModelLock
0949: * @return The ModelLock object associated with this model
0950: */
0951: public Lock getLock();
0952:
0953: /**
0954: Register a listener for model-changed events on this model. The methods on
0955: the listener will be called when API add/remove calls on the model succeed
0956: [in whole or in part].
0957: <p>
0958: The same listener may be registered many times; if so, it's methods will
0959: be called as many times as it's registered for each event.
0960:
0961: @see ModelChangedListener
0962: @return this model, for cascading
0963: */
0964: public Model register(ModelChangedListener listener);
0965:
0966: /**
0967: Unregister a listener from model-changed events on this model. The
0968: listener is dtached from the model. The model is returned to permit
0969: cascading. If the listener is not attached to the model, then nothing happens.
0970:
0971: @see ModelChangedListener
0972: @return this model, for cascading
0973: */
0974: public Model unregister(ModelChangedListener listener);
0975:
0976: /**
0977: Notify any listeners that the event e has occurred.
0978: @param e the event that has occurred
0979: */
0980: public Model notifyEvent(Object e);
0981:
0982: /**
0983: Remove all the statements from this model.
0984: */
0985: public Model removeAll();
0986:
0987: /**
0988: Remove all the statements matching (s, p, o) from this model.
0989: */
0990: public Model removeAll(Resource s, Property p, RDFNode r);
0991:
0992: /**
0993: Answer true iff .close() has been called on this Model.
0994: */
0995: public boolean isClosed();
0996:
0997: }
0998:
0999: /*
1000: * (c) Copyright 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
1001: * All rights reserved.
1002: *
1003: * Redistribution and use in source and binary forms, with or without
1004: * modification, are permitted provided that the following conditions
1005: * are met:
1006: * 1. Redistributions of source code must retain the above copyright
1007: * notice, this list of conditions and the following disclaimer.
1008: * 2. Redistributions in binary form must reproduce the above copyright
1009: * notice, this list of conditions and the following disclaimer in the
1010: * documentation and/or other materials provided with the distribution.
1011: * 3. The name of the author may not be used to endorse or promote products
1012: * derived from this software without specific prior written permission.
1013: * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
1014: * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
1015: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
1016: * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
1017: * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
1018: * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
1019: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
1020: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
1021: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
1022: * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1023: *
1024: * $Id: Model.java,v 1.71 2008/01/02 12:05:48 andy_seaborne Exp $
1025: */
|