Project

Profile

Help

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

he / src / main / c / Saxon.C.API / XQueryProcessor.h @ 9e416749

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
        clearProperties();
52
        clearParameters();
53
    }
54

    
55
    //!Set the initial context item for the query
56
    /**
57
      @param value - the initial context item, or nullptr if there is to be no initial context item
58
    */
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
     * @param value of the query parameter, or nullptr to clear a previously set value
76
     */
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
     * Assume the prefix or uri is nullptr.
191
     */
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
     * @param baseURI the static base URI; or nullptr to indicate that no base URI is available
222
     */
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
    * @return char*. Returns the main exception message if thrown otherwise return nullptr
234
    */
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

    
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
    
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 */
(22-22/55)