FileDocCategorySizeDatePackage
XPath.javaAPI DocJava SE 5 API18002Fri Aug 26 14:56:06 BST 2005com.sun.org.apache.xpath.internal

XPath

public class XPath extends Object implements Serializable, ExpressionOwner
The XPath class wraps an expression object and provides general services for execution of that expression.
xsl.usage
advanced

Fields Summary
private Expression
m_mainExp
The top of the expression tree.
String
m_patternString
The pattern string, mainly kept around for diagnostic purposes.
public static final int
SELECT
Represents a select type expression.
public static final int
MATCH
Represents a match type expression.
private static final boolean
DEBUG_MATCHES
Set to true to get diagnostic messages about the result of match pattern testing.
public static final double
MATCH_SCORE_NONE
The match score if no match is made.
public static final double
MATCH_SCORE_QNAME
The match score if the pattern has the form of a QName optionally preceded by an @ character.
public static final double
MATCH_SCORE_NSWILD
The match score if the pattern pattern has the form NCName:*.
public static final double
MATCH_SCORE_NODETEST
The match score if the pattern consists of just a NodeTest.
public static final double
MATCH_SCORE_OTHER
The match score if the pattern consists of something other than just a NodeTest or just a qname.
Constructors Summary
public XPath(String exprString, SourceLocator locator, PrefixResolver prefixResolver, int type, ErrorListener errorListener)
Construct an XPath object. (Needs review -sc) This method initializes an XPathParser/ Compiler and compiles the expression.

param
exprString The XPath expression.
param
locator The location of the expression, may be null.
param
prefixResolver A prefix resolver to use to resolve prefixes to namespace URIs.
param
type one of {@link #SELECT} or {@link #MATCH}.
param
errorListener The error listener, or null if default should be used.
throws
javax.xml.transform.TransformerException if syntax or other error.


                                                                                                       
   
                 
           
             
        
    if(null == errorListener)
      errorListener = new com.sun.org.apache.xml.internal.utils.DefaultErrorHandler();
    
    m_patternString = exprString;

    XPathParser parser = new XPathParser(errorListener, locator);
    Compiler compiler = new Compiler(errorListener, locator);

    if (SELECT == type)
      parser.initXPath(compiler, exprString, prefixResolver);
    else if (MATCH == type)
      parser.initMatchPattern(compiler, exprString, prefixResolver);
    else
      throw new RuntimeException(XSLMessages.createXPATHMessage(XPATHErrorResources.ER_CANNOT_DEAL_XPATH_TYPE, new Object[]{Integer.toString(type)})); //"Can not deal with XPath type: " + type);

    // System.out.println("----------------");
    Expression expr = compiler.compile(0);

    // System.out.println("expr: "+expr);
    this.setExpression(expr);
    
    if((null != locator) && locator instanceof ExpressionNode)
    {
    	expr.exprSetParent((ExpressionNode)locator);
    }
public XPath(String exprString, SourceLocator locator, PrefixResolver prefixResolver, int type)
Construct an XPath object. (Needs review -sc) This method initializes an XPathParser/ Compiler and compiles the expression.

param
exprString The XPath expression.
param
locator The location of the expression, may be null.
param
prefixResolver A prefix resolver to use to resolve prefixes to namespace URIs.
param
type one of {@link #SELECT} or {@link #MATCH}.
throws
javax.xml.transform.TransformerException if syntax or other error.

  
    this(exprString, locator, prefixResolver, type, null);
public XPath(Expression expr)
Construct an XPath object.

param
expr The Expression object.
throws
javax.xml.transform.TransformerException if syntax or other error.

  
    this.setExpression(expr);
Methods Summary
public voidassertion(boolean b, java.lang.String msg)
Tell the user of an assertion error, and probably throw an exception.

param
b If false, a runtime exception will be thrown.
param
msg The assertion message, which should be informative.
throws
RuntimeException if the b argument is false.


    if (!b)
    {
      String fMsg = XSLMessages.createXPATHMessage(
        XPATHErrorResources.ER_INCORRECT_PROGRAMMER_ASSERTION,
        new Object[]{ msg });

      throw new RuntimeException(fMsg);
    }
public booleanbool(com.sun.org.apache.xpath.internal.XPathContext xctxt, int contextNode, com.sun.org.apache.xml.internal.utils.PrefixResolver namespaceContext)
Given an expression and a context, evaluate the XPath and return the result.

param
xctxt The execution context.
param
contextNode The node that "." expresses.
param
namespaceContext The context in which namespaces in the XPath are supposed to be expanded.
throws
TransformerException thrown if the active ProblemListener decides the error condition is severe enough to halt processing.
throws
javax.xml.transform.TransformerException
xsl.usage
experimental


    xctxt.pushNamespaceContext(namespaceContext);

    xctxt.pushCurrentNodeAndExpression(contextNode, contextNode);

    try
    {
      return m_mainExp.bool(xctxt);
    }
    catch (TransformerException te)
    {
      te.setLocator(this.getLocator());
      ErrorListener el = xctxt.getErrorListener();
      if(null != el) // defensive, should never happen.
      {
        el.error(te);
      }
      else
        throw te;
    }
    catch (Exception e)
    {
      while (e instanceof com.sun.org.apache.xml.internal.utils.WrappedRuntimeException)
      {
        e = ((com.sun.org.apache.xml.internal.utils.WrappedRuntimeException) e).getException();
      }
      // e.printStackTrace();

      String msg = e.getMessage();
      
      if (msg == null || msg.length() == 0) {
           msg = XSLMessages.createXPATHMessage(
               XPATHErrorResources.ER_XPATH_ERROR, null);
     
      }        
      
      TransformerException te = new TransformerException(msg,
              getLocator(), e);
      ErrorListener el = xctxt.getErrorListener();
      // te.printStackTrace();
      if(null != el) // defensive, should never happen.
      {
        el.fatalError(te);
      }
      else
        throw te;
    }
    finally
    {
      xctxt.popNamespaceContext();

      xctxt.popCurrentNodeAndExpression();
    }

    return false;
public voidcallVisitors(com.sun.org.apache.xpath.internal.ExpressionOwner owner, com.sun.org.apache.xpath.internal.XPathVisitor visitor)
This will traverse the heararchy, calling the visitor for each member. If the called visitor method returns false, the subtree should not be called.

param
owner The owner of the visitor, where that path may be rewritten if needed.
param
visitor The visitor whose appropriate method will be called.

  	m_mainExp.callVisitors(this, visitor);
public voiderror(com.sun.org.apache.xpath.internal.XPathContext xctxt, int sourceNode, java.lang.String msg, java.lang.Object[] args)
Tell the user of an error, and probably throw an exception.

param
xctxt The XPath runtime context.
param
sourceNode Not used.
param
msg An error msgkey that corresponds to one of the constants found in {@link com.sun.org.apache.xpath.internal.res.XPATHErrorResources}, which is a key for a format string.
param
args An array of arguments represented in the format string, which may be null.
throws
TransformerException if the current ErrorListoner determines to throw an exception.


    String fmsg = XSLMessages.createXPATHMessage(msg, args);
    ErrorListener ehandler = xctxt.getErrorListener();

    if (null != ehandler)
    {
      ehandler.fatalError(new TransformerException(fmsg,
                              (SAXSourceLocator)xctxt.getSAXLocator()));
    }
    else
    {
      SourceLocator slocator = xctxt.getSAXLocator();
      System.out.println(fmsg + "; file " + slocator.getSystemId()
                         + "; line " + slocator.getLineNumber() + "; column "
                         + slocator.getColumnNumber());
    }
public com.sun.org.apache.xpath.internal.objects.XObjectexecute(com.sun.org.apache.xpath.internal.XPathContext xctxt, int contextNode, com.sun.org.apache.xml.internal.utils.PrefixResolver namespaceContext)
Given an expression and a context, evaluate the XPath and return the result.

param
xctxt The execution context.
param
contextNode The node that "." expresses.
param
namespaceContext The context in which namespaces in the XPath are supposed to be expanded.
throws
TransformerException thrown if the active ProblemListener decides the error condition is severe enough to halt processing.
throws
javax.xml.transform.TransformerException
xsl.usage
experimental


    xctxt.pushNamespaceContext(namespaceContext);

    xctxt.pushCurrentNodeAndExpression(contextNode, contextNode);

    XObject xobj = null;

    try
    {
      xobj = m_mainExp.execute(xctxt);
    }
    catch (TransformerException te)
    {
      te.setLocator(this.getLocator());
      ErrorListener el = xctxt.getErrorListener();
      if(null != el) // defensive, should never happen.
      {
        el.error(te);
      }
      else
        throw te;
    }
    catch (Exception e)
    {
      while (e instanceof com.sun.org.apache.xml.internal.utils.WrappedRuntimeException)
      {
        e = ((com.sun.org.apache.xml.internal.utils.WrappedRuntimeException) e).getException();
      }
      // e.printStackTrace();

      String msg = e.getMessage();
      
      if (msg == null || msg.length() == 0) {
           msg = XSLMessages.createXPATHMessage(
               XPATHErrorResources.ER_XPATH_ERROR, null);
     
      }  
      TransformerException te = new TransformerException(msg,
              getLocator(), e);
      ErrorListener el = xctxt.getErrorListener();
      // te.printStackTrace();
      if(null != el) // defensive, should never happen.
      {
        el.fatalError(te);
      }
      else
        throw te;
    }
    finally
    {
      xctxt.popNamespaceContext();

      xctxt.popCurrentNodeAndExpression();
    }

    return xobj;
public com.sun.org.apache.xpath.internal.objects.XObjectexecute(com.sun.org.apache.xpath.internal.XPathContext xctxt, org.w3c.dom.Node contextNode, com.sun.org.apache.xml.internal.utils.PrefixResolver namespaceContext)
Given an expression and a context, evaluate the XPath and return the result.

param
xctxt The execution context.
param
contextNode The node that "." expresses.
param
namespaceContext The context in which namespaces in the XPath are supposed to be expanded.
return
The result of the XPath or null if callbacks are used.
throws
TransformerException thrown if the error condition is severe enough to halt processing.
throws
javax.xml.transform.TransformerException
xsl.usage
experimental

    return execute(
          xctxt, xctxt.getDTMHandleFromNode(contextNode), 
          namespaceContext);
public voidfixupVariables(java.util.Vector vars, int globalsSize)
This function is used to fixup variables from QNames to stack frame indexes at stylesheet build time.

param
vars List of QNames that correspond to variables. This list should be searched backwards for the first qualified name that corresponds to the variable reference qname. The position of the QName in the vector from the start of the vector will be its position in the stack frame (but variables above the globalsTop value will need to be offset to the current stack frame).

    m_mainExp.fixupVariables(vars, globalsSize);
public com.sun.org.apache.xpath.internal.ExpressiongetExpression()
Get the raw Expression object that this class wraps.

return
the raw Expression object, which should not normally be null.

    return m_mainExp;
public javax.xml.transform.SourceLocatorgetLocator()
Get the SourceLocator on the expression object.

return
the SourceLocator on the expression object, which may be null.

    return m_mainExp;
public doublegetMatchScore(com.sun.org.apache.xpath.internal.XPathContext xctxt, int context)
Get the match score of the given node.

param
xctxt XPath runtime context.
param
context The current source tree context node.
return
score, one of {@link #MATCH_SCORE_NODETEST}, {@link #MATCH_SCORE_NONE}, {@link #MATCH_SCORE_OTHER}, or {@link #MATCH_SCORE_QNAME}.
throws
javax.xml.transform.TransformerException


                                           
       
           
  

    xctxt.pushCurrentNode(context);
    xctxt.pushCurrentExpressionNode(context);

    try
    {
      XObject score = m_mainExp.execute(xctxt);

      if (DEBUG_MATCHES)
      {
        DTM dtm = xctxt.getDTM(context);
        System.out.println("score: " + score.num() + " for "
                           + dtm.getNodeName(context) + " for xpath "
                           + this.getPatternString());
      }

      return score.num();
    }
    finally
    {
      xctxt.popCurrentNode();
      xctxt.popCurrentExpressionNode();
    }

    // return XPath.MATCH_SCORE_NONE;
public java.lang.StringgetPatternString()
Return the XPath string associated with this object.

return
the XPath string associated with this object.

    return m_patternString;
public voidinstallFunction(java.lang.String name, int funcIndex, com.sun.org.apache.xpath.internal.functions.Function func)
Install a built-in function.

param
name The unqualified name of the function; not currently used.
param
funcIndex The index of the function in the table.
param
func An Implementation of an XPath Function object.
return
the position of the function in the internal index.

    FunctionTable.installFunction(func, funcIndex);
public voidsetExpression(com.sun.org.apache.xpath.internal.Expression exp)
Set the raw expression object for this object.

param
exp the raw Expression object, which should not normally be null.

  	if(null != m_mainExp)
    	exp.exprSetParent(m_mainExp.exprGetParent()); // a bit bogus
    m_mainExp = exp;
public voidwarn(com.sun.org.apache.xpath.internal.XPathContext xctxt, int sourceNode, java.lang.String msg, java.lang.Object[] args)
Warn the user of an problem.

param
xctxt The XPath runtime context.
param
sourceNode Not used.
param
msg An error msgkey that corresponds to one of the constants found in {@link com.sun.org.apache.xpath.internal.res.XPATHErrorResources}, which is a key for a format string.
param
args An array of arguments represented in the format string, which may be null.
throws
TransformerException if the current ErrorListoner determines to throw an exception.


    String fmsg = XSLMessages.createXPATHWarning(msg, args);
    ErrorListener ehandler = xctxt.getErrorListener();

    if (null != ehandler)
    {

      // TO DO: Need to get stylesheet Locator from here.
      ehandler.warning(new TransformerException(fmsg, (SAXSourceLocator)xctxt.getSAXLocator()));
    }