Project

Profile

Help

Download (9.56 KB) Statistics
| Branch: | Revision:

he / src / main / c / Saxon.C.API / XQueryProcessor.h @ 55b80284

1 72bf04c6 Norman Walsh
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
2 ead48a5d O'Neil Delpratt
// Copyright (c) 2020 Saxonica Limited.
3 72bf04c6 Norman Walsh
// This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
4
// If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
5
// This Source Code Form is "Incompatible With Secondary Licenses", as defined by the Mozilla Public License, v. 2.0.
6
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
7
8
#ifndef SAXON_XQUERY_H
9
#define SAXON_XQUERY_H
10
11
12
13
#include "SaxonProcessor.h"
14
#include <string>
15
16
17
18
class SaxonProcessor;
19
class SaxonApiException;
20
class XdmValue;
21
class XdmItem;
22
23
/*! An <code>XQueryProcessor</code> represents factory to compile, load and execute the query.
24
 * <p/>
25
 */
26
class XQueryProcessor {
27
public:
28
29
    //! Default constructor.
30
    XQueryProcessor();
31
32
    //! Constructor with the SaxonProcessor supplied.
33
    /*!
34
     * @param SaxonProcessor - Supplied pointer to the SaxonProcessor object
35
     * @param cwd - set the current working directory. Default is the empty string
36
    */
37
    XQueryProcessor(SaxonProcessor *p, std::string cwd="");
38
39
    /**
40
      * XQueryProcessor copy constructor.
41
      * @param other - XsltProcessor
42
    */
43
    XQueryProcessor(const XQueryProcessor &other);
44
45
    /**
46
      * Clone the XQueryProcessor with the same internal state, which can be used in separate threads.
47
    */
48
    XQueryProcessor * clone();
49
50
    ~XQueryProcessor(){
51
        clearProperties();
52
        clearParameters();
53
    }
54
55
    //!Set the initial context item for the query
56
    /**
57 ead48a5d O'Neil Delpratt
      @param value - the initial context item, or nullptr if there is to be no initial context item
58 72bf04c6 Norman Walsh
    */
59
    void setContextItem(XdmItem * value);
60
61
    /**
62
     * Set the output file where the result is sent
63
    */
64
    void setOutputFile(const char* outfile);
65
66
    /**
67
     * Set the source from file for the query.
68
    */
69
    void setContextItemFromFile(const char * filename); 
70
71
    /**
72
     * Set a parameter value used in the query
73
     *s
74
     * @param name  of the parameter, as a string. For namespaced parameter use the JAXP solution i.e. "{uri}name"
75 ead48a5d O'Neil Delpratt
     * @param value of the query parameter, or nullptr to clear a previously set value
76 72bf04c6 Norman Walsh
     */
77
    void setParameter(const char * name, XdmValue*value);
78
79
80
    /**
81
     * Remove a parameter (name, value) pair
82
     *
83
     * @param namespacei currently not used
84
     * @param name  of the parameter
85
     * @return bool - outcome of the romoval
86
     */
87
    bool removeParameter(const char * name);
88
89
    /**
90
     * Set a property specific to the processor in use. 
91
     * XQueryProcessor: set serialization properties (names start with '!' i.e. name "!method" -> "xml")
92
     * 'o':outfile name, 's': source as file name
93
     * 'q': query file name, 'q': current by name, 'qs': string form of the query, 'base': set the base URI of the query, 'dtd': set DTD validation 'on' or 'off'
94
     * @param name of the property
95
     * @param value of the property
96
     */
97
    void setProperty(const char * name, const char * value);
98
99
    /**
100
     * Clear parameter values set
101
     *  @param deleteValues.  Individual pointers to XdmValue objects have to be deleted in the calling program
102
     * Default behaviour (false) is to leave XdmValues in memory
103
     *  true then XdmValues are deleted
104
     */
105
    void clearParameters(bool deleteValues=false);
106
107
    /**
108
     * Clear property values set
109
     */
110
    void clearProperties();
111
112
113
    /**
114
     * Say whether the query is allowed to be updating. XQuery update syntax will be rejected
115
     * during query compilation unless this flag is set. XQuery Update is supported only under Saxon-EE.
116
     * @param updating - true if the query is allowed to use the XQuery Update facility
117
     *                 (requires Saxon-EE). If set to false, the query must not be an updating query. If set
118
     *                 to true, it may be either an updating or a non-updating query.
119
     */
120
    void setUpdating(bool updating);
121
122
123
    //!Perform the Query to file.
124
    /**
125
     * The result is is saved to file
126
     *
127
     * @param infilename - The file name of the source document
128
     * @param ofilename - The file name of where result will be stored
129
     * @param query - The query as string representation. TODO check
130
     */
131
    void executeQueryToFile(const char * infilename, const char * ofilename, const char * query);
132
133
     //!Perform the Query to a XdmValue representation.
134
    /**
135
     * @param infilename - The file name of the source document
136
     * @param ofilename - The file name of where result will be stored
137
     * @param query - The query as string representation
138
     * @return XdmValue - result of the the query as a XdmValue 
139
     */
140
    XdmValue * executeQueryToValue(const char * infilename, const char * query);
141
142
143
    //!Perform the Query to a string representation.
144
    /**
145
     * @param infilename - The file name of the source document
146
     * @param query - The query as string representation
147
     * @return char array - result of as a string
148
     */
149
    const char * executeQueryToString(const char * infilename, const char * query);
150
151
    //!Execute the Query cached.
152
    /** 
153
     * The use of the context item would have had to be set in advance
154
     * @return XdmValue of the result
155
     *
156
     */
157
    XdmValue * runQueryToValue();
158
159
    /**
160
     * Execute the Query cached.
161
     * The use of the context item would have had to be set in advance
162
     * @return Result as a string (i.e. pointer array of char)
163
     *
164
     */
165
    const char * runQueryToString();
166
167
168
    //!Execute the Query cached to file.
169
    /**
170
     * The use of the context item would have had to be set in advance
171
     * Assume the output filename has been set in advance
172
     * @return Result as a string (i.e. pointer array of char)
173
     *
174
     */
175
    void runQueryToFile();
176
177
     //!Declare a namespace binding.
178
     /**
179
     * Declare a namespace binding as part of the static context for queries compiled using this
180
     * XQueryCompiler. This binding may be overridden by a binding that appears in the query prolog.
181
     * The namespace binding will form part of the static context of the query, but it will not be copied
182
     * into result trees unless the prefix is actually used in an element or attribute name.
183
     *
184
     * @param prefix The namespace prefix. If the value is a zero-length string, this method sets the default
185
     *               namespace for elements and types.
186
     * @param uri    The namespace URI. It is possible to specify a zero-length string to "undeclare" a namespace;
187
     *               in this case the prefix will not be available for use, except in the case where the prefix
188
     *               is also a zero length string, in which case the absence of a prefix implies that the name
189
     *               is in no namespace.
190 ead48a5d O'Neil Delpratt
     * Assume the prefix or uri is nullptr.
191 72bf04c6 Norman Walsh
     */
192
    void declareNamespace(const char *prefix, const char * uri);
193
194
195
     //!Get all parameters as a std::map
196
     /**
197
      * @return std::map  - map of the parameters string->XdmValue* 
198
     */
199
     std::map<std::string,XdmValue*>& getParameters();
200
201
      //!Get all properties as a std::map
202
     /**
203
      * @return std::map map of the properties string->string 
204
     */
205
     std::map<std::string,std::string>& getProperties();
206
207
     //!Compile a query supplied as a file name.
208
    /**
209
     * The supplied query is cached for later execution.
210
     */
211
    void setQueryFile(const char* filename);
212
213
     //!Compile a query supplied as a string.
214
    /**
215
     * The supplied query is cached for later execution.
216
     */
217
    void setQueryContent(const char* content);
218
219
     //!Set the static base URI for the query
220
     /**
221 ead48a5d O'Neil Delpratt
     * @param baseURI the static base URI; or nullptr to indicate that no base URI is available
222 72bf04c6 Norman Walsh
     */
223
    void setQueryBaseURI(const char * baseURI);
224
225
    /**
226
     * set the current working directory
227
    */
228
   void setcwd(const char* cwd);
229
230
231
     //! Check for exception thrown.
232
   /**
233 ead48a5d O'Neil Delpratt
    * @return char*. Returns the main exception message if thrown otherwise return nullptr
234 72bf04c6 Norman Walsh
    */
235
    const char* checkException();
236
237
    /**
238
     * Checks for pending exceptions without creating a local reference to the exception object
239
     * @return bool - true when there is a pending exception; otherwise return false
240
    */
241
    bool exceptionOccurred();
242
243
    //! Clear any exception thrown
244
    void exceptionClear();
245
246
247
     //! Get the ith error message if there are any error
248
    /**
249
     * A transformation may have a number of errors reported against it.
250
     * @return char* - The message of the exception
251
    */
252
    const char * getErrorMessage();
253
254
255
     //! Get the i'th error code if there are any error
256
    /**
257
     * After the execution of the query there may be a number of errors reported against it.
258
     * @return char* - The error code of the exception.
259
    */
260
    const char * getErrorCode();
261 79d12c83 O'Neil Delpratt
262
    //! Get the SaxonApiException object created when we have an error
263
    /**
264
     * After the execution of the processor if there is an error, then a SaxonApiException is created.
265
     * NULL returned if there is no error.
266
     * @return SaxomApiException object of the exception thrown.
267
     */
268
    SaxonApiException * getException();
269 72bf04c6 Norman Walsh
    
270
271
private:
272
    std::string cwdXQ; /*!< current working directory */
273
        SaxonProcessor * proc;
274
        jclass  cppClass;
275
        jobject cppXQ;
276
        std::map<std::string,XdmValue*> parameters; /*!< map of parameters used for the transformation as (string, value) pairs */
277
        std::map<std::string,std::string> properties; /*!< map of properties used for the transformation as (string, string) pairs */
278
        SaxonApiException * exception;
279
};
280
281
#endif /* SAXON_XQUERY_H */