model.java

Jena推理机

/*
  (c) Copyright 2002, 2003, 2004, 2005, 2006, 2007 Hewlett-Packard Development Company, LP
  [See end of file]
  $Id: Model.java,v 1.68 2007/01/15 12:41:14 jeremy_carroll Exp $
*/

package com.hp.hpl.jena.rdf.model;

import com.hp.hpl.jena.datatypes.*;
import com.hp.hpl.jena.shared.*;

import java.io.*;
import java.util.*;

/**
    An RDF Model.
<p>
    An RDF model is a set of Statements.  Methods are provided for creating
    resources, properties and literals and the Statements which link them,
    for adding statements to and removing them from a model, for
    querying a model and set operations for combining models.
<p>
    Models may create Resources [URI nodes and bnodes]. Creating a Resource does
    <i>not</i> make the Resource visible to the model; Resources are only "in" Models
    if Statements about them are added to the Model. Similarly the only way to "remove"
    a Resource from a Model is to remove all the Statements that mention it.
<p>
    When a Resource or Literal is created by a Model, the Model is free to re-use an
    existing Resource or Literal object with the correct values, or it may create a fresh
    one. [All Jena RDFNodes and Statements are immutable, so this is generally safe.]
<p>
    This interface defines a set of primitive methods.  A set of
    convenience methods which extends this interface, e.g. performing
    automatic type conversions and support for enhanced resources,
    is defined in {@link ModelCon}.</P>

 <h2>System Properties</h2>


 <h3>Firewalls and Proxies</h3>

    Some of the methods, e.g. the read methods, may have to traverse a
    firewall.  This can be accomplished using the standard java method
    of setting system properties.  To use a socks proxy, include on the
    java command line:</p>
 * <blockquote>
 *   -DsocksProxyHost=[your-proxy-domain-name-or-ip-address]
 * </blockquote>
 *
 * <p>To use an http proxy, include on the command line:</p>
 * <blockquote>
 * -DproxySet=true -DproxyHost=[your-proxy] -DproxyPort=[your-proxy-port-number]
 * </blockquote>
 *
 * <p>Alternatively, these properties can be set programatically, e.g.</p>
 *
 * <code><pre>
 *   System.getProperties().put("proxySet","true");
 *   System.getProperties().put("proxyHost","proxy.hostname");
 *   System.getProperties().put("proxyPort",port_number);
 * </pre></code>
 *
 * @author bwm
 * @version $Name:  $ $Revision: 1.68 $Date: 2007/01/15 12:41:14 $'
 */
public interface Model
    extends ModelCon, ModelGraphInterface,
        RDFReaderF, RDFWriterF, PrefixMapping, ModelLock
{


    /**
     * size will return the number of statements in a concrete model,
     * for a virtualized model such as one created by an inference engine,
     * it will return an estimated lower bound for the numberof statements
     * in the model but it is possible for a subsequent listStatements on
     * such a model to discover more statements than size() indicated.
     * @return the number of statements in a concrete model or an estimated
     * lower bound on the number of statements in an virtualized model
     */
	long size() ;

    /**
        Answer true iff the model contains no explicit statements (ie it's size is zero,
        listStatements() would deliver the empty iterator).

        @return true iff the model contains no explicit statements.
    */
    boolean isEmpty();

	/** List all resources which are subjects of statements.
	 *
	 * <p>Subsequent operations on those resource may modify this model.</p>

	 * @return an iterator over a set of resources which are subjects of statements
	 *         in the model. .remove() is not implemented on this iterator.
	 *
	 */
	ResIterator listSubjects() ;

	/**
        (You probably don't want this method; more likely you want the
        PrefixMapping methods that Model supports.) List the namespaces used
        by predicates and types in the model. This method is really intended
        for use by the RDF/XML writer, which needs to know these
        namespaces to generate correct and vaguely pretty XML.
    <p>
        The namespaces returned are those of (a) every URI used as a property in the
        model and (b) those of every URI that appears as the object of an rdf:type statement.
    <p>
        Note that the notion of "namespace" used here is not that of an XML
        prefix-namespace, but just of the minimal legal left part of a URI
        (see Util.splitNamespace for details). If you want the RDF/XML (or
        N3) namespaces, treat the Model as a PrefixMapping.

       @see com.hp.hpl.jena.shared.PrefixMapping
	   @return an iterator over every predicate and type namespace
	 */
	NsIterator listNameSpaces() ;

	/**
        Return a Resource instance with the given URI in this model. <i>This method
        behaves identically to <code>createResource(String)</code></i> and exists as
        legacy: createResource is now capable of, and allowed to, reuse existing objects.
    <p>
        Subsequent operations on the returned object may modify this model.
	   @return a resource instance
	   @param uri the URI of the resource
    */
	Resource getResource(String uri) ;

	/**
        Return a Property instance with the given URI in this model. <i>This method
        behaves identically to <code>createProperty(String,String)</code></i> and exists as
        legacy: createProperty is now capable of, and allowed to, reuse existing objects.
    <p>
        Subsequent operations on the returned property may modify this model.
	   @return a property linked to this model
	   @param nameSpace the RDF namespace of the property
	   @param localName the localName of the property in its namespace
	*/
	Property getProperty(String nameSpace, String localName);

	/**
        Create a new anonymous resource whose model is this model. This bnode will
        have a new AnonId distinct from any allocated by any other call of this method.
    <p>
        Subsequent operations on the returned resource may modify this model.
	   @return a new anonymous resource linked to this model.
	*/
	public Resource createResource() ;

    /**
        Create a blank node resource with a specified identifier. The resulting bnode
        will be equal to any other bnode with the same AnonId (even if they are in
        separate models - be warned). The intended use for this method is to allow
        bnode round-tripping between Jena models and other representations.
    <p>
        This method may return an existing bnode with the correct AnonId and model, or it
        may construct a fresh one, as it sees fit.
    <p>
        Operations on the result may modify this model
        @param id the identifier to use for this blank node
        @return a blank node with that identifier
    */
    public Resource createResource( AnonId id );

	/**
        Create a new resource associated with this model. If the uri string is null, this creates
        a bnode, as per <code>createResource()</code>. Otherwise it creates a URI node.
        A URI resource is .equals() to any other URI Resource with the same URI (even in
        a different model - be warned).
    <p>
        This method may return an existing Resource with the correct URI and model, or it
        may construct a fresh one, as it sees fit.
    <p>
        Operations on the result Resource may change this model.

	   @param uri the URI of the resource to be created
	   @return a new resource linked to this model.
	*/
	public Resource createResource( String uri ) ;

	/**
        Create a property with a given URI composed from a namespace part and a
        localname part by concatenating the strings.
    <p>
        This method may return an existing property with the correct URI and model, or it
        may construct a fresh one, as it sees fit.
	 <p>
        Subsequent operations on the returned property may modify this model.
	   @param nameSpace the nameSpace of the property
	   @param localName the name of the property within its namespace
	   @return a property instance
	*/
	public Property createProperty(String nameSpace, String localName);

	/**
        Create an untyped literal from a String value with a specified language.
	   @param v the lexical form of the literal
	   @param language the language associated with the literal
	   @return a new literal representing the value v with the given language
	 */

	public Literal createLiteral(String v, String language);

    /**
     * @deprecated since Jena2. It is no longer legal to have a language
     * tag on a well-formed XMLLiteral. Use the 2-argument form of
     * {@link #createLiteral(String, boolean) createLiteral} instead.
     *
     *   Create a literal from a String value with a specified language. An existing literal
     *   of the right value may be returned, or a fresh one created.
     *  @param v the lexical form of the literal
     *  @param language the language associated with the literal
     *  @param wellFormed true if the Literal is well formed XML
     *  @return a new literal representing the value v with the given language
     */
    public Literal createLiteral(String v, String language, boolean wellFormed);

    /**
        Create a literal from a String value. An existing literal
        of the right value may be returned, or a fresh one created.
        The use of the wellFormed flag is to create typed literals of
        type rdf:XMLLiteral, without error checking. This should
        only be use when the lexical form is known to already be
        in exclusive canonical XML.

       @param v the lexical form of the literal
       @param wellFormed true if the Literal is well formed XML, in the lexical space of rdf:XMLLiteral
       @return a new literal
     */
    public Literal createLiteral(String v, boolean wellFormed);

    /**
        Build a typed literal from its lexical form. The
        lexical form will be parsed now and the value stored. If
        the form is not legal this will throw an exception.
        <p>
        Note that in preview releases of Jena2 it was also possible to specify
        a language type. Changes to the RDF specification mean that this is no longer
        legal except for plain literals. To create a plain literal with a language tag
        use {@link #createLiteral(String, String) createLiteral}.

        @param lex the lexical form of the literal
        @param dtype the type of the literal, null for old style "plain" literals
        @throws DatatypeFormatException if lex is not a legal form of dtype
     */
    public Literal createTypedLiteral(String lex, RDFDatatype dtype);

    /**
     * Build a typed literal from its value form.
     * <p>
     * Note that in preview releases of Jena2 it was also possible to specify
     *   a language type. Changes to the RDF specification mean that this is no longer
     *   legal except for plain literals. To create a plain literal with a language tag
     *   use {@link #createLiteral(String, String) createLiteral}.
     * </p>
     * @param value the value of the literal
     * @param dtype the type of the literal, null for old style "plain" literals
     */
    public Literal createTypedLiteral(Object value, RDFDatatype dtype);

    /**
     * Build a typed literal label from its value form using
     * whatever datatype is currently registered as the the default
     * representation for this java class. No language tag is supplied.
     * @param value the literal value to encapsulate
     */
    public Literal createTypedLiteral(Object value);

	/**
       Create a Statement instance. (Creating a statement does not add it to the set of
       statements in the model; see Model::add). This method may return an existing
       Statement with the correct components and model, or it may construct a fresh one,
       as it sees fit.
    <p>
	   Subsequent operations on the statement or any of its parts may modify this model.
	   @param s the subject of the statement
	   @param p the predicate of the statement
	   @param o the object of the statement
	   @return the new statement
	*/
	public Statement createStatement( Resource s, Property p, RDFNode o );

    /**
        Answer a new empty list. This is equivalent to a list consisting only
        of <code>rdf:nil</code>.
        @return An RDF-encoded list of no elements
    */
    public RDFList createList();


    /**
     * <p>Answer a new list containing the resources from the given iterator, in order.</p>
     * @param members An iterator, each value of which is expected to be an RDFNode
     * @return An RDF-encoded list of the elements of the iterator
     */
    public RDFList createList( Iterator members );


    /**
     * <p>Answer a new list containing the nodes from the given array, in order</p>
     * @param members An array of RDF nodes that will be the members of the list
     * @return An RDF-encoded list
     */
    public RDFList createList( RDFNode[] members );


	/** Add a statement to this model.
	 * @return This model.
	 * @param s The statement to be added.

	 */
	Model add(Statement s) ;

    /**
        Add all the statements to the Model, using through the bulk update interface.

        @param statements the array of statements to add
        @return this model, to allow cascading
    */
    Model add( Statement [] statements );

    /**
        Remove all the statements from the Model, using the bulk update interface.
        @param statements the array of statements to be added
        @return this model, to allow cascading
    */
    Model remove( Statement [] statements );

    /**
        add all the statements in the List to this Model, going through the bulk
        update interface (which means turning them into triples in one form or
        another).
        @param statements a List of Statements
        @return this model, to allow cascading
    */
    Model add( List statements );

    /**