All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.exist.xmldb.EXistXQueryService Maven / Gradle / Ivy

There is a newer version: 6.3.0
Show newest version
/*
 * eXist Open Source Native XML Database
 * Copyright (C) 2001-2017 The eXist Project
 * http://exist-db.org
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software Foundation
 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
package org.exist.xmldb;

import java.io.Writer;

import org.exist.source.Source;
import org.exist.xquery.XPathException;
import org.xmldb.api.base.CompiledExpression;
import org.xmldb.api.base.ResourceSet;
import org.xmldb.api.base.XMLDBException;
import org.xmldb.api.modules.XMLResource;
import org.xmldb.api.modules.XQueryService;

/**
 * Execute XQuery expressions on the database.
 *
 * This interface is similar to {@link org.xmldb.api.modules.XPathQueryService}, but
 * provides additional methods to compile an XQuery into an internal representation, which
 * can be executed repeatedly. Since XQuery scripts can be very large, compiling an expression
 * in advance can save a lot of time.
 *
 * @author Wolfgang Meier
 */
public interface EXistXQueryService extends XQueryService {

    /**
     * Execute the specified query and return the results as a {@link ResourceSet}.
     *
     * @param query The query to execute.
     *
     * @return The query results
     *
     * @throws XMLDBException If an error occurs whilst executing the query
     */
    ResourceSet query(String query) throws XMLDBException;

    /**
     * Process a query based on the result of a previous query.
     * The XMLResource contains the result received from a previous
     * query.
     *
     * @param res an XMLResource as obtained from a previous query.
     * @param query the XPath query
     *
     * @return The query results
     *
     * @throws XMLDBException If an error occurs whilst executing the query
     */
    ResourceSet query(XMLResource res, String query) throws XMLDBException;

    /**
     * Compiles the specified XQuery and returns a handle to the compiled
     * code, which can then be passed to {@link #execute(CompiledExpression)}.
     *
     * Note: {@link CompiledExpression} is not thread safe. Please make sure you don't
     * call the same compiled expression from two threads at the same time.
     *
     * @param query The XQuery to compile
     *
     * @return a compiled representation of the query
     *
     * @throws XMLDBException if an error occurs whilst compiling the query
     */
    @Override
    CompiledExpression compile(String query) throws XMLDBException;

    /**
     * Tries to compile the specified XQuery and returns a handle to the compiled
     * code, which can then be passed to {@link #execute(CompiledExpression)}.
     * If a static error is detected, an {@link XPathException} will be thrown.
     *
     * @param query The XQuery to compile
     *
     * @return a compiled representation of the query
     *
     * @throws XMLDBException if an error occurs whilst compiling the query,
     *     or a static error is detected.
     * @throws XPathException if an error occurs whilst executing the query.
     */
    CompiledExpression compileAndCheck(String query) throws XMLDBException, XPathException;

    /**
     * Executes the query.
     *
     * @param querySource The source of the query
     *
     * @return The results of the query
     *
     * @throws XMLDBException if an error occurs whilst executing the query
     */
    ResourceSet execute(Source querySource) throws XMLDBException;

    /**
     * Execute a compiled XQuery.
     *
     * The implementation should pass all namespaces and variables declared through
     * {@link EXistXQueryService} to the compiled XQuery code.
     *
     * Note: {@link CompiledExpression} is not thread safe. Please make sure you don't
     * call the same compiled expression from two threads at the same time.
     *
     * @param compiledExpression a compiled query
     *
     * @return The results of the query
     *
     * @throws XMLDBException if an error occurs whilst executing the query
     */
    @Override
    ResourceSet execute(CompiledExpression compiledExpression) throws XMLDBException;

    /**
     * Execute a compiled query based on the result of a previous query.
     * The XMLResource contains the result received from a previous
     * query.
     *
     * The implementation should pass all namespaces and variables declared through
     * {@link EXistXQueryService} to the compiled XQuery code.
     *
     * Note: {@link CompiledExpression} is not thread safe. Please make sure you don't
     * call the same compiled expression from two threads at the same time.
     *
     * @param res an XMLResource as obtained from a previous query.
     * @param compiledExpression a compiled query
     *
     * @return The results of the query
     *
     * @throws XMLDBException if an error occurs whilst executing the query
     */
    ResourceSet execute(XMLResource res, CompiledExpression compiledExpression) throws XMLDBException;

    /**
     * Returns the URI string associated with prefix from
     * the internal namespace map. If prefix is null or empty the
     * URI for the default namespace will be returned. If a mapping for the
     * prefix can not be found null is returned.
     *
     * @param prefix The prefix to retrieve from the namespace map.
     *
     * @return The URI associated with prefix
     *
     * @throws XMLDBException with expected error codes.
     *     ErrorCodes.VENDOR_ERROR for any vendor
     *     specific errors that occur.
     */
    @Override
    String getNamespace(String prefix) throws XMLDBException;

    /**
     * Sets a namespace mapping in the internal namespace map used to evaluate
     * queries. If prefix is null or empty the default namespace is
     * associated with the provided URI. A null or empty uri results
     * in an exception being thrown.
     *
     * @param prefix The prefix to set in the map. If
     *     prefix is empty or null the
     *     default namespace will be associated with the provided URI.
     * @param namespace The URI for the namespace to be associated with prefix.
     *
     * @throws XMLDBException with expected error codes.
     *     ErrorCodes.VENDOR_ERROR for any vendor
     *     specific errors that occur.
     */
    @Override
    void setNamespace(String prefix, String namespace) throws XMLDBException;

    /**
     * Removes the namespace mapping associated with prefix from
     * the internal namespace map. If prefix is null or empty the
     * mapping for the default namespace will be removed.
     *
     * @param ns The prefix to remove from the namespace map. If
     *     prefix is null or empty the mapping for the default
     *     namespace will be removed.
     *
     * @throws XMLDBException with expected error codes.
     *     ErrorCodes.VENDOR_ERROR for any vendor
     *     specific errors that occur.
     */
    @Override
    void removeNamespace(String ns) throws XMLDBException;

    /**
     * Declare a global, external XQuery variable and assign a value to it. The variable
     * has the same status as a variable declare through the declare variable
     * statement in the XQuery prolog.
     *
     * The variable can be referenced inside the XQuery expression as
     * $variable. For example, if you declare a variable with
     *
     * 
     * 	declareVariable("name", "HAMLET");
     * 
* * you may use the variable in an XQuery expression as follows: * *
     * 	//SPEECH[SPEAKER=$name]
     * 
* * Any Java object may be passed as initial value. The implementation will try * to map the Java object into a corresponding XQuery value. In particular, all * basic Java types (Integer, Long, Double, String) should be mapped into the corresponding XML * Schema atomic types. A Java array is mapped to an XQuery sequence. The implemenation * should also recognize all DOM node types. * * As a special case, an XMLResource as obtained from a {@link ResourceSet} will be * converted into a node. * * @param qname a valid QName by which the variable is identified. Any * prefix should have been mapped to a namespace, using {@link #setNamespace(String, String)}. * For example, if a variable is called x:name, a prefix/namespace mapping should have * been defined for prefix x before calling this method. * @param initialValue the initial value, which is assigned to the variable * * @throws XMLDBException if an error occurs whilst declaring the variable. */ @Override void declareVariable(String qname, Object initialValue) throws XMLDBException; /** * Clears any previously declared variables * * @throws XMLDBException if an error occurs whilst clearning the variables. */ void clearVariables() throws XMLDBException; /** * Enable or disable XPath 1.0 compatibility mode. In XPath 1.0 * compatibility mode, some XQuery expressions will behave different. * In particular, additional automatic type conversions will be applied * to the operands of numeric operators. * * @param backwardsCompatible true to enable backward compatibility mode. */ @Override void setXPathCompatibility(boolean backwardsCompatible); @Override void setModuleLoadPath(String path); /** * Return a diagnostic dump of the query. The query should have been executed * before calling this function. * * @param compiledExpression The compiled query to dump. * @param writer a writer which received a dump of the query. * * @throws XMLDBException if an error occurs whilst dumping the query */ void dump(CompiledExpression compiledExpression, Writer writer) throws XMLDBException; }




© 2015 - 2025 Weber Informatics LLC | Privacy Policy