digquerytranslator.java

Jena推理机

/*****************************************************************************
 * Source code information
 * -----------------------
 * Original author    Ian Dickinson, HP Labs Bristol
 * Author email       [e-mail]
 * Package            Jena 2
 * Web                http://sourceforge.net/projects/jena/
 * Created            July 19th 2003
 * Filename           $RCSfile: DIGQueryTranslator.java,v $
 * Revision           $Revision: 1.19 $
 * Release status     $State: Exp $
 *
 * Last modified on   $Date: 2007/01/02 11:49:27 $
 *               by   $Author: andy_seaborne $
 *
 * (c) Copyright 2001, 2002, 2003, 2004, 2005, 2006, 2007 Hewlett-Packard Development Company, LP
 * [See end of file]
 * ****************************************************************************/

// Package
///////////////
package com.hp.hpl.jena.reasoner.dig;


// Imports
///////////////
import java.util.*;
import java.util.Iterator;
import java.util.List;

import org.apache.commons.logging.LogFactory;
import org.w3c.dom.Document;
import org.w3c.dom.Element;

import com.hp.hpl.jena.graph.*;
import com.hp.hpl.jena.rdf.model.Model;
import com.hp.hpl.jena.reasoner.TriplePattern;
import com.hp.hpl.jena.reasoner.rulesys.Node_RuleVariable;
import com.hp.hpl.jena.util.iterator.*;
import com.hp.hpl.jena.util.xml.SimpleXMLPath;
import com.hp.hpl.jena.util.xml.SimpleXMLPathElement;


/**
 * <p>
 * Base class for translators that map incoming RDF find patterns to DIG queries.
 * </p>
 *
 * @author Ian Dickinson, HP Labs (<a href="mailto:[e-mail]">email</a>)
 * @version Release @release@ ($Id: DIGQueryTranslator.java,v 1.19 2007/01/02 11:49:27 andy_seaborne Exp $)
 */
public abstract class DIGQueryTranslator {
    // Constants
    //////////////////////////////////

    public static final String ALL = "*";


    // Static variables
    //////////////////////////////////


    // Instance variables
    //////////////////////////////////

    /** The node that the incoming subject must match */
    private Node m_subject;

    /** The node that the incoming object must match */
    private Node m_object;

    /** The node that the incoming predicate must match */
    private Node m_pred;


    // Constructors
    //////////////////////////////////

    /**
     * <p>Construct an abstract translator, given the URI's of nodes to match against
     * or null to represent
     */
    public DIGQueryTranslator( String subject, String predicate, String object ) {
        m_subject = mapNode( subject );
        m_pred    = mapNode( predicate );
        m_object  = mapNode( object );
    }


    // External signature methods
    //////////////////////////////////

    /**
     * <p>Translate the given pattern to a DIG query, and pass it on to the DIG
     * adapter as a query.  Translate the results of the query back to a
     * triple stream via an extended iterator. Assumes this method is called
     * contingent on a successful {@link #trigger}.</p>
     * @param pattern The pattern to translate to a DIG query
     * @param da The DIG adapter through which we communicate with a DIG reasoner
     */
    public ExtendedIterator find( TriplePattern pattern, DIGAdapter da ) {
        DIGConnection dc = da.getConnection();

        // pose the query to the dig reasoner
        Document query = translatePattern( pattern, da );
        if (query == null) {
            LogFactory.getLog( getClass() ).warn( "Could not find pattern translator for nested DIG query " + pattern );
        }
        Document response = da.getConnection().sendDigVerb( query, da.getProfile() );

        boolean warn = dc.warningCheck( response );
        if (warn) {
            for (Iterator i = dc.getWarnings();  i.hasNext(); ) {
                LogFactory.getLog( getClass() ).warn( i.next() );
            }
        }

        // translate the response back to triples
        return translateResponse( response, pattern, da );
    }


    /**
     * <p>Translate the given pattern (with given premises)
     * to a DIG query, and pass it on to the DIG
     * adapter as a query.  Translate the results of the query back to a
     * triple stream via an extended iterator.</p>
     * @param pattern The pattern to translate to a DIG query
     * @param da The DIG adapter through which we communicate with a DIG reasoner
     * @param premises Model conveying additional information about the resources
     * in the subject or object
     */
    public ExtendedIterator find( TriplePattern pattern, DIGAdapter da, Model premises ) {
        DIGConnection dc = da.getConnection();

        // pose the query to the dig reasoner
        Document query = translatePattern( pattern, da, premises );
        if (query == null) {
            LogFactory.getLog( getClass() ).warn( "Could not find pattern translator for nested DIG query " + pattern );
            return NullIterator.instance;
        }
        else {
            Document response = da.getConnection().sendDigVerb( query, da.getProfile() );

            boolean warn = dc.warningCheck( response );
            if (warn) {
                for (Iterator i = dc.getWarnings();  i.hasNext(); ) {
                    LogFactory.getLog( getClass() ).warn( i.next() );
                }
            }

            // translate the response back to triples
            return translateResponse( response, pattern, da );
        }
    }


    /**
     * <p>Answer true if this translator applies to the given triple pattern.</p>
     * @param pattern An incoming patter to match against
     * @param da The current dig adapter
     * @param premises An optional Model that is used to convey the statements in the additional
     * premises to the query
     * @return True if this translator applies to the pattern.
     */
    public boolean trigger( TriplePattern pattern, DIGAdapter da, Model premises ) {
        return trigger( m_subject, pattern.getSubject(), premises ) &&
               trigger( m_object, pattern.getObject(), premises )   &&
               trigger( m_pred, pattern.getPredicate(), premises )  &&
               checkTriple( pattern, da, premises );
    }


    /**
     * <p>An optional post-trigger check on the consituents of the triple pattern. By default,
     * delegates to a check on each of the subjec, object and predicate.  However, this method
     * may be overridden by sub-classes to provide a more context-sensitive test.</p>
     * @param pattern The triple pattern
     * @param da The current dig adapter
     * @param premises Model denoting premises to the query, or null
     * @return True if the pattern conforms to the prerequisites for a given translation step
     */
    public boolean checkTriple( TriplePattern pattern, DIGAdapter da, Model premises ) {
        return checkSubject( pattern.getSubject(), da, premises )       &&
               checkObject( pattern.getObject(), da, premises )         &&
               checkPredicate( pattern.getPredicate(), da, premises );

    }


    /**
     * <p>Additional test on the subject of the incoming find pattern. Default
     * is to always match</p>
     * @param subject The subject resource from the incoming pattern
     * @param da The current dig adapter
     * @param premises A model that conveys additional information about the premises
     * of the query, which might assist the check to suceed or fail. By default it
     * is ignored.
     * @return True if this subject matches the trigger condition expressed by this translator instance
     */
    public boolean checkSubject( Node subject, DIGAdapter da, Model premises ) {
        return true;
    }


    /**
     * <p>Additional test on the object of the incoming find pattern. Default
     * is to always match</p>
     * @param object The object resource from the incoming pattern
     * @param da The current dig adapter
     * @param premises A model that conveys additional information about the premises
     * of the query, which might assist the check to suceed or fail. By default it
     * is ignored.
     * @return True if this object matches the trigger condition expressed by this translator instance
     */
    public boolean checkObject( Node object, DIGAdapter da, Model premises ) {
        return true;
    }


    /**
     * <p>Additional test on the predicate of the incoming find pattern. Default
     * is to always match</p>
     * @param pred The predicate resource from the incoming pattern
     * @param da The current dig adapter
     * @param premises A model that conveys additional information about the premises
     * of the query, which might assist the check to suceed or fail. By default it
     * is ignored.
     * @return True if this predicate matches the trigger condition expressed by this translator instance
     */
    public boolean checkPredicate( Node pred, DIGAdapter da, Model premises ) {
        return true;
    }


    /**
     * <p>Answer an XML document that presents the translation of the query into DIG query language.</p>
     */
    public abstract Document translatePattern( TriplePattern query, DIGAdapter da );

    /**
     * <p>Answer an XML document that presents the translation of the query into DIG query language,
     * given that either the subject or object may be expressions defined by the statements
     * in the premises model.</p>
     */
    public abstract Document translatePattern( TriplePattern pattern, DIGAdapter da, Model premises );

    /**
     * <p>Answer an extended iterator over the triples that result from translatig the given DIG response
     * to RDF.</p>
     */
    public final ExtendedIterator translateResponse( Document response, TriplePattern query, DIGAdapter da ) {
        ExtendedIterator i = translateResponseHook( response, query, da );
        Filter f = getResultsTripleFilter( query );
        return (f == null) ? i : i.filterKeep( f );
    }


    // Internal implementation methods
    //////////////////////////////////

    /**
     * <p>Answer an extended iterator over the triples that result from translatig the given DIG response
     * to RDF.</p>
     */
    protected abstract ExtendedIterator translateResponseHook( Document response, TriplePattern query, DIGAdapter da );


    /**
     * <p>Answer a node corresponding to the given URI.</p>
     * @param uri A node URI, or the special string *, or null.
     * @return A Jena Node corresponding to the given URI
     */
    protected Node mapNode( String uri ) {
        if (uri == null) {
            return null;
        }
        else {
            return (uri.equals( ALL )) ? Node_RuleVariable.WILD : Node.createURI( uri );
        }
    }