digadapter.java

jena2.5.4推理机系统的一种最基本实现 HP实验室出品

     * @return An object containing the results of querying the reasoner for its identity
     * and capabilities
     */
    public DIGIdentifier getDigIdentifier() {
        Document getIDVerb = getConnection().createDigVerb( DIGProfile.GET_IDENTIFIER, getProfile() );
        return new DigIdentifierImpl( getConnection().sendDigVerb( getIDVerb, getProfile() ) );
    }


    /**
     * <p>Upload the entire contents of the local knowledge base (OWL/DAML model)
     * to the DIG reasoner, using a single large TELL verb.</p>
     * @return True if the ontology model was uploaded to DIG without any warnings.  Recent warnings
     * are available via {@link #getRecentWarnings}
     * @exception DigReasonerException If the upload fails for any reason. The error message from
     * the DIG reasoner will be returned.
     */
    public boolean uploadKB() {
        // ensure first that we have a KB identifier
        getConnection().bindKB( false, getProfile() );

        // now tell the existing KB contents
        Document kbDIG = translateKbToDig();

        Document response = getConnection().sendDigVerb( kbDIG, getProfile() );
        return !getConnection().warningCheck( response );
    }



    /**
     * <p>Answer an iterator over any recent warnings returned from from the remote DIG reasoner.</p>
     * @return An iterator over any warnings; if there are no warnings the return
     * value will be an iterator that returns <code>hasNext()</code> = false.
     */
    public Iterator getRecentWarnings() {
        return getConnection().getWarnings();
    }


    /**
     * <p>Answer an XML document that contains the DIG translation of the local graph, wrapped
     * as a tell verb</p>
     * @return An XML document containing the tell verb
     */
    public Document translateKbToDig() {
        Document tell = getConnection().createDigVerb( DIGProfile.TELLS, getProfile() );
        Element root = tell.getDocumentElement();

        addNamedEntities( root );
        translateClasses( root );
        translateRoles( root );
        translateAttributes( root );
        translateIndividuals( root );
        translateAllDifferentAxioms( root );

        return tell;
    }


    /**
     * <p>Clear the old contents of the DIG knowledge base</p>
     */
    public void resetKB() {
        getConnection().bindKB( true, getProfile() );

        // reset the name caches
        m_indNames.clear();
        m_indNamesAsked = false;
        m_conceptNames.clear();
        m_conceptNamesAsked = false;
        m_roleNames.clear();
        m_roleNamesAsked = false;
    }


    /**
     * <p>Answer this adapter's connection to the database.</p>
     * @return The DIG connector this adapter is using, or null if the connection has
     * been closed.
     */
    public DIGConnection getConnection() {
        return m_connection;
    }


    /**
     * <p>Close this adapter, and release the connector to the external DIG KB.</p>
     */
    public void close() {
        getConnection().release();
        m_connection = null;
    }


    /**
     * <p>Basic pattern lookup interface - answer an iterator over the triples
     * matching the given pattern.  Where possible, this query will first be
     * given to the external reasoner, with the local graph used to generate
     * supplemental bindings.</p>
     * @param pattern a TriplePattern to be matched against the data
     * @return An ExtendedIterator over all Triples in the data set
     *  that match the pattern
     */
    public ExtendedIterator find( TriplePattern pattern ) {
        DIGQueryTranslator tr = getQueryTranslator( pattern, null );

        ExtendedIterator remote = (tr == null) ? null : tr.find( pattern, this );

        com.hp.hpl.jena.graph.Node pSubj = normaliseNode( pattern.getSubject() );
        com.hp.hpl.jena.graph.Node pPred = normaliseNode( pattern.getPredicate() );
        com.hp.hpl.jena.graph.Node pObj = normaliseNode( pattern.getObject() );
        ExtendedIterator local = m_sourceData.getGraph().find( pSubj, pPred, pObj );

        // if we have a remote iterator, prepend to the local one and drop duplicates
        ExtendedIterator i = (remote == null) ? local : remote.andThen( local );

        // add the axioms if specified
        i = (m_axioms == null) ? i : i.andThen( m_axioms.getGraph().find( pSubj, pPred, pObj ) );

        // make sure we don't have duplicates
        return UniqueExtendedIterator.create( i );
    }


    /**
     * <p>Basic pattern lookup interface - answer an iterator over the triples
     * matching the given (S,P,O) pattern, given also some premises for the
     * query.  Where possible, this query will first be
     * given to the external reasoner, with the local graph used to generate
     * supplemental bindings.</p>
     * @param pattern a TriplePattern to be matched against the data
     * @param premises A model containing additional premises for the find query,
     * typically used to allow the subject and/or object to be an expression
     * rather than just a simple node
     * @return An ExtendedIterator over all Triples in the data set
     *  that match the pattern
     */
    public ExtendedIterator find( TriplePattern pattern, Model premises ) {
        DIGQueryTranslator tr = getQueryTranslator( pattern, premises );

        if (tr == null) {
            LogFactory.getLog( getClass() ).debug( "Could not find DIG query translator for " + pattern );
        }

        ExtendedIterator remote = (tr == null) ? null : tr.find( pattern, this, premises );

        com.hp.hpl.jena.graph.Node pSubj = normaliseNode( pattern.getSubject() );
        com.hp.hpl.jena.graph.Node pPred = normaliseNode( pattern.getPredicate() );
        com.hp.hpl.jena.graph.Node pObj = normaliseNode( pattern.getObject() );
        ExtendedIterator local = m_sourceData.getGraph().find( pSubj, pPred, pObj );

        // if we have a remote iterator, prepend to the local one and drop duplicates
        ExtendedIterator i = (remote == null) ? local : remote.andThen( local );

        // add the axioms if specified
        i = (m_axioms == null) ? i : i.andThen( m_axioms.getGraph().find( pSubj, pPred, pObj ) );

        // make sure we don't have duplicates
        return UniqueExtendedIterator.create( i );
    }


    /**
     * <p>Answer the query translator that matches the given pattern, if any</p>
     * @param pattern The triple pattern that has been received
     * @param premises A model containing the premises to a query (e.g. a class expression)
     * @return A DIG translator that can translate this pattern to a DIG query,
     * or null if no matches.
     */
    public DIGQueryTranslator getQueryTranslator( TriplePattern pattern, Model premises ) {
        for (int i = 0;  i < s_queryTable.length;  i++) {
            DIGQueryTranslator dqt = s_queryTable[i];

            if (dqt.trigger( pattern, this, premises )) {
                return dqt;
            }
        }

        return null;
    }


    /**
     * <p>Answer the graph of local (source) data.</p>
     * @return The graph containing the local source data.
     */
    public Graph getGraph() {
        return m_sourceData.getGraph();
    }


    /**
     * <p>Answer an identifier for a resource, named or bNode</p>
     * @param r A resource
     * @return A unique identifier for the resource as a string, which will either
     * be the resource URI for named resources, or a unique ID string for bNodes
     */
    public String getResourceID( Resource r ) {
        return getNodeID( r.asNode() );
    }


    /**
     * <p>Answer an identifier for a node, named or anon</p>
     * @param n An RDF node
     * @return A unique identifier for the node as a string, which will either
     * be the resource URI for named nodes, or a unique ID string for bNodes
     */
    public String getNodeID( com.hp.hpl.jena.graph.Node n ) {
        if (n.isBlank()) {
            return ANON_MARKER + n.getBlankNodeId().toString();
        }
        else {
            return n.getURI();
        }
    }


    /**
     * <p>Add a DIG reference to the class identifed in the source graph by the given Jena
     * graph Node to the given XML element.  If the class is a named class, this will be
     * a <code>&lt;catom&gt;</code> element, otherwise it will be a class description axiom.
     * Assumes that the instance variable <code>m_sourceData</code> provides the statements that
     * further define the class if it is a description not a name.
     * </p>
     * @param elem The parent XML element to which the class description will be attached
     * @param node An RDF graph node representing a class we wish to describe.
     */
    public void addClassDescription( Element elem, com.hp.hpl.jena.graph.Node node ) {
        addClassDescription( elem, node, m_sourceData );
    }


    /**
     * <p>Add a DIG reference to the class identifed in the source graph by the given Jena
     * graph Node to the given XML element.  If the class is a named class, this will be
     * a <code>&lt;catom&gt;</code> element, otherwise it will be a class description axiom.
     * </p>
     * @param elem The parent XML element to which the class description will be attached
     * @param node An RDF graph node representing a class we wish to describe.
     * @param sourceData A model containing the statements about the given class description
     * resource
     */
    public void addClassDescription( Element elem, com.hp.hpl.jena.graph.Node node, Model sourceData ) {
        Model m = (sourceData == null) ? m_sourceData : sourceData;
        addClassDescription( elem, (Resource) m.getRDFNode( node ), m );
    }


    /**
     * <p>Add a DIG reference to the class identifed in the source graph by the given Jena
     * resource to the given XML element.  If the class is a named class, this will be
     * a <code>&lt;catom&gt;</code> element, otherwise it will be a class description axiom.</p>
     * @param elem The parent XML element to which the class description will be attached
     * @param res An RDF resource representing a class we wish to describe.
     * @param sourceData A model containing the statements about the given class description
     * resource
     */
    public void addClassDescription( Element elem, Resource res, Model sourceData ) {
        // ensure we have a resource from the source data model
        Resource cls = (res.getModel() != sourceData) ? sourceData.getResource( res.getURI() ) : res;

        if (!cls.isAnon() || m_conceptNames.contains( getNodeID( cls.asNode() ))) {
            // a named class, or an already known bNode
            translateClassIdentifier( elem, cls );
        }
        else {
            // a new bNode introducing a class expression
            translateClassDescription( elem, (OntClass) cls.as( OntClass.class ), sourceData );
        }
    }


    /**
     * <p>Answer true if the given node corresponds to one of the individuals known to
     * the DIG reasoner.</p>
     * @param node A node to test
     * @return True if <code>node</code> is a known individual
     */
    public boolean isIndividual( com.hp.hpl.jena.graph.Node node ) {
        return node.isConcrete() && !node.isLiteral() && getKnownIndividuals().contains( getNodeID( node ) );
    }


    /**
     * <p>Answer true if the given node corresponds to one of the roles known to
     * the DIG reasoner.</p>
     * @param node A node to test
     * @param premises A model defining premises that may encode more information about
     * node, or may be null
     * @return True if <code>node</code> is a known role