Project

Profile

Help

How to connect?
Download (9.57 KB) Statistics
| Branch: | Revision:

he / src / main / c / Saxon.C.API / XQueryProcessor.h @ 5d25f10d

1
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
2
// Copyright (c) 2020 Saxonica Limited.
3
// 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

    
52
    //!Set the initial context item for the query
53
    /**
54
      @param value - the initial context item, or nullptr if there is to be no initial context item
55
    */
56
    void setContextItem(XdmItem * value);
57

    
58
    /**
59
     * Set the output file where the result is sent
60
    */
61
    void setOutputFile(const char* outfile);
62

    
63
    /**
64
     * Set the source from file for the query.
65
    */
66
    void setContextItemFromFile(const char * filename); 
67

    
68
    /**
69
     * Set a parameter value used in the query
70
     *s
71
     * @param name  of the parameter, as a string. For namespaced parameter use the JAXP solution i.e. "{uri}name"
72
     * @param value of the query parameter, or nullptr to clear a previously set value
73
     */
74
    void setParameter(const char * name, XdmValue*value);
75

    
76

    
77
    /**
78
     * Remove a parameter (name, value) pair
79
     *
80
     * @param namespacei currently not used
81
     * @param name  of the parameter
82
     * @return bool - outcome of the romoval
83
     */
84
    bool removeParameter(const char * name);
85

    
86
    /**
87
     * Set a property specific to the processor in use. 
88
     * XQueryProcessor: set serialization properties (names start with '!' i.e. name "!method" -> "xml")
89
     * 'o':outfile name, 's': source as file name
90
     * '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'
91
     * @param name of the property
92
     * @param value of the property
93
     */
94
    void setProperty(const char * name, const char * value);
95

    
96
    /**
97
     * Clear parameter values set
98
     *  @param deleteValues.  Individual pointers to XdmValue objects have to be deleted in the calling program
99
     * Default behaviour (false) is to leave XdmValues in memory
100
     *  true then XdmValues are deleted
101
     */
102
    void clearParameters(bool deleteValues=false);
103

    
104
    /**
105
     * Clear property values set
106
     */
107
    void clearProperties();
108

    
109

    
110
    /**
111
     * Say whether the query is allowed to be updating. XQuery update syntax will be rejected
112
     * during query compilation unless this flag is set. XQuery Update is supported only under Saxon-EE.
113
     * @param updating - true if the query is allowed to use the XQuery Update facility
114
     *                 (requires Saxon-EE). If set to false, the query must not be an updating query. If set
115
     *                 to true, it may be either an updating or a non-updating query.
116
     */
117
    void setUpdating(bool updating);
118

    
119

    
120
    //!Perform the Query to file.
121
    /**
122
     * The result is is saved to file
123
     *
124
     * @param infilename - The file name of the source document
125
     * @param ofilename - The file name of where result will be stored
126
     * @param query - The query as string representation. TODO check
127
     */
128
    void executeQueryToFile(const char * infilename, const char * ofilename, const char * query);
129

    
130
     //!Perform the Query to a XdmValue representation.
131
    /**
132
     * @param infilename - The file name of the source document
133
     * @param ofilename - The file name of where result will be stored
134
     * @param query - The query as string representation
135
     * @return XdmValue - result of the the query as a XdmValue 
136
     */
137
    XdmValue * executeQueryToValue(const char * infilename, const char * query);
138

    
139

    
140
    //!Perform the Query to a string representation.
141
    /**
142
     * @param infilename - The file name of the source document
143
     * @param query - The query as string representation
144
     * @return char array - result of as a string
145
     */
146
    const char * executeQueryToString(const char * infilename, const char * query);
147

    
148
    //!Execute the Query cached.
149
    /** 
150
     * The use of the context item would have had to be set in advance
151
     * @return XdmValue of the result
152
     *
153
     */
154
    XdmValue * runQueryToValue();
155

    
156
    /**
157
     * Execute the Query cached.
158
     * The use of the context item would have had to be set in advance
159
     * @return Result as a string (i.e. pointer array of char)
160
     *
161
     */
162
    const char * runQueryToString();
163

    
164

    
165
    //!Execute the Query cached to file.
166
    /**
167
     * The use of the context item would have had to be set in advance
168
     * Assume the output filename has been set in advance
169
     * @return Result as a string (i.e. pointer array of char)
170
     *
171
     */
172
    void runQueryToFile();
173

    
174
     //!Declare a namespace binding.
175
     /**
176
     * Declare a namespace binding as part of the static context for queries compiled using this
177
     * XQueryCompiler. This binding may be overridden by a binding that appears in the query prolog.
178
     * The namespace binding will form part of the static context of the query, but it will not be copied
179
     * into result trees unless the prefix is actually used in an element or attribute name.
180
     *
181
     * @param prefix The namespace prefix. If the value is a zero-length string, this method sets the default
182
     *               namespace for elements and types.
183
     * @param uri    The namespace URI. It is possible to specify a zero-length string to "undeclare" a namespace;
184
     *               in this case the prefix will not be available for use, except in the case where the prefix
185
     *               is also a zero length string, in which case the absence of a prefix implies that the name
186
     *               is in no namespace.
187
     * Assume the prefix or uri is nullptr.
188
     */
189
    void declareNamespace(const char *prefix, const char * uri);
190

    
191

    
192
     //!Get all parameters as a std::map
193
     /**
194
      * @return std::map  - map of the parameters string->XdmValue* 
195
     */
196
     std::map<std::string,XdmValue*>& getParameters();
197

    
198
      //!Get all properties as a std::map
199
     /**
200
      * @return std::map map of the properties string->string 
201
     */
202
     std::map<std::string,std::string>& getProperties();
203

    
204
     //!Compile a query supplied as a file name.
205
    /**
206
     * The supplied query is cached for later execution.
207
     */
208
    void setQueryFile(const char* filename);
209

    
210
     //!Compile a query supplied as a string.
211
    /**
212
     * The supplied query is cached for later execution.
213
     */
214
    void setQueryContent(const char* content);
215

    
216
     //!Set the static base URI for the query
217
     /**
218
     * @param baseURI the static base URI; or nullptr to indicate that no base URI is available
219
     */
220
    void setQueryBaseURI(const char * baseURI);
221

    
222
    /**
223
     * set the current working directory
224
    */
225
   void setcwd(const char* cwd);
226

    
227

    
228
     //! Check for exception thrown.
229
   /**
230
    * @return char*. Returns the main exception message if thrown otherwise return nullptr
231
    */
232
    const char* checkException();
233

    
234
    /**
235
     * Checks for pending exceptions without creating a local reference to the exception object
236
     * @return bool - true when there is a pending exception; otherwise return false
237
    */
238
    bool exceptionOccurred();
239

    
240
    //! Clear any exception thrown
241
    void exceptionClear();
242

    
243

    
244
     //! Get the ith error message if there are any error
245
    /**
246
     * A transformation may have a number of errors reported against it.
247
     * @return char* - The message of the exception
248
    */
249
    const char * getErrorMessage();
250

    
251

    
252
     //! Get the i'th error code if there are any error
253
    /**
254
     * After the execution of the query there may be a number of errors reported against it.
255
     * @return char* - The error code of the exception.
256
    */
257
    const char * getErrorCode();
258

    
259
    //! Get the SaxonApiException object created when we have an error
260
    /**
261
     * After the execution of the processor if there is an error, then a SaxonApiException is created.
262
     * NULL returned if there is no error.
263
     * @return SaxomApiException object of the exception thrown.
264
     */
265
    SaxonApiException * getException();
266
    
267

    
268
private:
269

    
270
    void createException(const char * message=nullptr);
271

    
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 */
(23-23/56)