Project

Profile

Help

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

he / src / main / c / Saxon.C.API / Xslt30Processor.h @ 02e2c377

1 72bf04c6 Norman Walsh
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
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_XSLT30_H
9
#define SAXON_XSLT30_H
10
11
12
#include "SaxonProcessor.h"
13
//#include "XdmValue.h"
14
#include <string>
15
16
class SaxonProcessor;
17
class SaxonApiException;
18
class XsltExecutable;
19
class XdmValue;
20
class XdmItem;
21
class XdmNode;
22
23
/*! An <code>Xslt30Processor</code> represents factory to compile, load and execute a stylesheet.
24
 * It is possible to cache the context and the stylesheet in the <code>Xslt30Processor</code>.
25
 */
26
class Xslt30Processor {
27
28 ead48a5d O'Neil Delpratt
    friend class XsltExecutable;
29
30 72bf04c6 Norman Walsh
public:
31
32
    //! Default constructor.
33
    /*!
34
      Creates a Saxon-HE product
35
    */
36
    Xslt30Processor();
37
38
    //! Constructor with the SaxonProcessor supplied.
39
    /*!
40
      @param proc - Supplied pointer to the SaxonProcessor object
41
      cwd - The current working directory
42
    */
43
    Xslt30Processor(SaxonProcessor* proc, std::string cwd="");
44
45
        /**
46
         * Xslt30Processor copy constructor.
47
         * @param other - Xslt30Processor
48
         */
49
    Xslt30Processor(const Xslt30Processor &other);
50
51
     ~Xslt30Processor();
52
53
        //! Get the SaxonProcessor object
54
        /**
55
        * @return SaxonProcessor - Pointer to the object
56
        */
57
    SaxonProcessor * getSaxonProcessor(){return proc;}
58
59
    //!set the current working directory (cwd). This method also applies to the
60
    // static base URI for XSLT stylesheets when supplied as lexical string.
61
    /**
62
      * The cwd is used to set the base URI is part of the static context, and is used to resolve
63
      * any relative URIs appearing within XSLT.
64
      * @param cwd - Current working directory
65
     */
66
   void setcwd(const char* cwd);
67
68
69
70
    /**
71
    * Say whether just-in-time compilation of template rules should be used.
72
    * @param jit true if just-in-time compilation is to be enabled. With this option enabled,
73
    *            static analysis of a template rule is deferred until the first time that the
74
    *            template is matched. This can improve performance when many template
75
    *            rules are rarely used during the course of a particular transformation; however,
76
    *            it means that static errors in the stylesheet will not necessarily cause the
77
    *            {@link #compile(Source)} method to throw an exception (errors in code that is
78
    *            actually executed will still be notified to the registered <code>ErrorListener</code>
79
    *            or <code>ErrorList</code>, but this may happen after the {@link #compile(Source)}
80
    *            method returns). This option is enabled by default in Saxon-EE, and is not available
81
    *            in Saxon-HE or Saxon-PE.
82
    *            <p><b>Recommendation:</b> disable this option unless you are confident that the
83
    *            stylesheet you are compiling is error-free.</p>
84
    */
85
    void setJustInTimeCompilation(bool jit);
86
87
88
    /**
89
     * Set the value of a stylesheet parameter. Static (compile-time) parameters must be provided using
90
     * this method on the XsltCompiler object, prior to stylesheet compilation. Non-static parameters
91
     * may also be provided using this method if their values will not vary from one transformation
92
     * to another.
93
     *
94
     * @param name  the name of the stylesheet parameter, as a string. For namespaced parameter use the JAXP solution i.e. "{uri}name"
95 ead48a5d O'Neil Delpratt
     * @param value the value of the stylesheet parameter, or nullptr to clear a previously set value
96 72bf04c6 Norman Walsh
     * @param _static For static (compile-time) parameters we set this flag to true, which means the parameter is
97
     * must be set on the XsltCompiler object, prior to stylesheet compilation. The default is false. Non-static parameters
98
     * may also be provided.
99
     */
100
    void setParameter(const char* name, XdmValue*value);
101
102
103
104
    /**
105
     * Get a parameter value by name
106
     * @param name - Specified paramater name to get
107
     * @return XdmValue
108
    */
109
     XdmValue* getParameter(const char* name);
110
111
112
    /**
113
     * Remove a parameter (name, value) pair from a stylesheet
114
     *
115
     * @param name  the name of the stylesheet parameter
116
     * @return bool - outcome of the romoval
117
     */
118
    bool removeParameter(const char* name);
119
120
        //! Get all parameters as a std::map
121
     /**
122
      * 
123
      * Please note that the key name has been prefixed with 'param:', for example 'param:name'
124
      * @return std:map with key as string name mapped to XdmValue. 
125
      * 
126
     */
127
     std::map<std::string,XdmValue*>& getParameters();
128
129
130
    //!Clear parameter values set
131
    /**
132
     * Default behaviour (false) is to leave XdmValues in memory
133
     *  true then XdmValues are deleted
134
     *  @param deleteValues.  Individual pointers to XdmValue objects have to be deleted in the calling program
135
     */
136
    void clearParameters(bool deleteValues=false);
137
138
139
    /**
140
    * Utility method for working with Saxon/C on Python
141
    */
142
    XdmValue ** createXdmValueArray(int len){
143
        return (new XdmValue*[len]);
144
    }
145
146
    /**
147
    * Utility method for working with Saxon/C on Python
148
    */
149
    char** createCharArray(int len){
150
        return (new char*[len]);
151
    }
152
153
    void deleteXdmValueArray(XdmValue ** arr, int len){
154
        for(int i =0; i< len; i++) {
155
                //delete arr[i];        
156
        }
157
        delete [] arr;
158
    }
159
160
    /**
161
     * This method gives users the option to switch on or off the <code>xsl:message</code> feature. It is also possible
162
     * to send the <code>xsl:message</code> outputs to file given by file name.
163
     * @param show - boolean to indicate if xsl:message should be outputted. Default is on.
164
     * @param  filename - If the filename argument is present then the xsl:message output is appended to the given
165
     *                    filename with location cwd+filename
166
     */
167 ead48a5d O'Neil Delpratt
    void setupXslMessage(bool show, const char* filename=nullptr);
168 72bf04c6 Norman Walsh
169
170
171
      //!Perform a one shot transformation.
172
    /**
173
     * The result is stored in the supplied outputfile.
174
     *
175
     * @param sourcefile - The file name of the source document
176 ead48a5d O'Neil Delpratt
     * @param stylesheetfile - The file name of the stylesheet document. If nullptr the most recently compiled stylesheet is used
177 72bf04c6 Norman Walsh
     * @param outputfile - The file name where results will be stored
178
     */
179
    void transformFileToFile(const char* sourcefile, const char* stylesheetfile, const char* outputfile); 
180
181
        //!Perform a one shot transformation.
182
    /**
183
     * The result is returned as a string
184
     *
185
     * @param sourcefile - The file name of the source document
186 ead48a5d O'Neil Delpratt
     * @param stylesheetfile - The file name of the stylesheet document. If nullptr the most recently compiled stylesheet is used
187 72bf04c6 Norman Walsh
     * @return char array - result of the transformation
188
     */
189
    const char * transformFileToString(const char* sourcefile, const char* stylesheetfile);
190
191
    /**
192
     * Perform a one shot transformation. The result is returned as an XdmValue
193
     *
194
     * @param sourcefile - The file name of the source document
195 ead48a5d O'Neil Delpratt
     * @param stylesheetfile - The file name of the stylesheet document. If nullptr the most recently compiled stylesheet is used
196 72bf04c6 Norman Walsh
     * @return XdmValue - result of the transformation
197
     */
198
    XdmValue * transformFileToValue(const char* sourcefile, const char* stylesheetfile);
199
200
201
     //! compile a stylesheet file.
202
    /**
203
     * The compiled stylesheet is cached and available for execution later.
204
     * @param stylesheet  - The file name of the stylesheet document.
205
     * @return an XsltExecutable, which represents the compiled stylesheet. The XsltExecutable
206
     * is immutable and thread-safe; it may be used to run multiple transformations, in series or concurrently.
207
     */
208
    XsltExecutable * compileFromFile(const char* stylesheet);
209
210
     //!compile a stylesheet received as a string.
211
    /**
212
     * 
213
     * The compiled stylesheet is cached and available for execution later.
214
     * @param stylesheet as a lexical string representation
215
     * @return an XsltExecutable, which represents the compiled stylesheet. The XsltExecutable
216
     * is immutable and thread-safe; it may be used to run multiple transformations, in series or concurrently.
217
     */
218
    XsltExecutable * compileFromString(const char* stylesheet);
219
220
221
222
     //! Get the stylesheet associated
223
     /* via the xml-stylesheet processing instruction (see
224
     * http://www.w3.org/TR/xml-stylesheet/) with the document
225
     * document specified in the source parameter, and that match
226
     * the given criteria.  If there are several suitable xml-stylesheet
227
     * processing instructions, then the returned Source will identify
228
     * a synthesized stylesheet module that imports all the referenced
229
     * stylesheet module.*/
230
    /**
231
     * The compiled stylesheet is cached and available for execution later.
232
     * @param sourceFile  - The file name of the XML document.
233
     * @return an XsltExecutable, which represents the compiled stylesheet. The XsltExecutable
234
     * is immutable and thread-safe; it may be used to run multiple transformations, in series or concurrently.
235
     */
236
    XsltExecutable * compileFromAssociatedFile(const char* sourceFile);
237
238
239
     //!compile a stylesheet received as a string and save to an exported file (SEF).
240
    /**
241
     * 
242
     * The compiled stylesheet is saved as SEF to file store
243
     * @param stylesheet as a lexical string representation
244
     * @param filename - the file to which the compiled package should be saved
245
     */
246
    void compileFromStringAndSave(const char* stylesheet, const char* filename);
247
248
249
     //!compile a stylesheet received as a file and save to an exported file (SEF).
250
    /**
251
     * 
252
     * The compiled stylesheet is saved as SEF to file store
253
     * @param xslFilename - file name of the stylesheet
254
     * @param filename - the file to which the compiled package should be saved
255
     */
256
    void compileFromFileAndSave(const char* xslFilename, const char* filename);
257
258
259
     //!compile a stylesheet received as an XdmNode.
260
    /**
261
     * The compiled stylesheet is cached and available for execution later.
262
     * @param stylesheet as a lexical string representation
263
     * @param filename - the file to which the compiled package should be saved
264
     */
265
    void compileFromXdmNodeAndSave(XdmNode * node, const char* filename);
266
267
     //!compile a stylesheet received as an XdmNode.
268
    /**
269
     * The compiled stylesheet is cached and available for execution later.
270
     * @param stylesheet as a lexical string representation
271
     * @return an XsltExecutable, which represents the compiled stylesheet. The XsltExecutable
272
     * is immutable and thread-safe; it may be used to run multiple transformations, in series or concurrently.
273
     */
274
    XsltExecutable * compileFromXdmNode(XdmNode * node);
275
276
277
    /**
278
     * Checks for pending exceptions without creating a local reference to the exception object
279
     * @return bool - true when there is a pending exception; otherwise return false
280
    */
281
    bool exceptionOccurred();
282
283
284 79d12c83 O'Neil Delpratt
    //! Get the SaxonApiException object created when we have an error
285
    /**
286
     * After the execution of the processor if there is an error, then a SaxonApiException is created.
287
     * NULL returned if there is no error.
288
     * @return SaxomApiException object of the exception thrown.
289
     */
290
    SaxonApiException * getException();
291 72bf04c6 Norman Walsh
292
293
     //! Clear any exception thrown
294
    void exceptionClear();
295
296
297
     //! Get the ith error message if there are any error
298
    /**
299
     * A transformation may have a number of errors reported against it.
300
     * @return char* - The message of the exception
301
    */
302
    const char * getErrorMessage();
303
304
     //! Get the ith error code if there are any error
305
    /**
306
     * A transformation may have a number of errors reported against it.
307
     * @return char* - The error code of the exception. The error code are related to the specific specification
308
    */
309
    const char * getErrorCode();
310
311
312
313 ead48a5d O'Neil Delpratt
314
315
316 72bf04c6 Norman Walsh
private:
317 4ee4355d O'Neil Delpratt
318
    void createException(const char * message=nullptr);
319
320 72bf04c6 Norman Walsh
        SaxonProcessor* proc;/*! */
321
        jclass  cppClass;
322
        jobject cppXT;
323
    std::string cwdXT; /*!< current working directory */
324
        bool tunnel, jitCompilation;
325
        std::map<std::string,XdmValue*> parameters; /*!< map of parameters used for the transformation as (string, value) pairs */
326
    SaxonApiException * exception;
327 ead48a5d O'Neil Delpratt
328
329 72bf04c6 Norman Walsh
};
330
331
332
#endif /* SAXON_XSLT30_H */