Project

Profile

Help

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

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

1
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
2
// Copyright (c) 2015 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_XSLT_H
9
#define SAXON_XSLT_H
10

    
11

    
12
#include "SaxonProcessor.h"
13
//#include "XdmValue.h"
14
#include <string>
15

    
16
class SaxonProcessor;
17
class SaxonApiException;
18
class XdmValue;
19
class XdmItem;
20
class XdmNode;
21

    
22
/*! An <code>XsltProcessor</code> represents factory to compile, load and execute a stylesheet.
23
 * It is possible to cache the context and the stylesheet in the <code>XsltProcessor</code>.
24
 */
25
class XsltProcessor {
26

    
27
public:
28

    
29
    //! Default constructor.
30
    /*!
31
      Creates a Saxon-HE product
32
    */
33
    XsltProcessor();
34

    
35
    //! Constructor with the SaxonProcessor supplied.
36
    /*!
37
      @param proc - Supplied pointer to the SaxonProcessor object
38
      cwd - The current working directory
39
    */
40
    XsltProcessor(SaxonProcessor* proc, std::string cwd="");
41

    
42
        /**
43
         * XsltProcessor copy constructor.
44
         * @param other - XsltProcessor
45
         */
46
    XsltProcessor(const XsltProcessor &other);
47

    
48
        /**
49
         * Clone the XsltProcessor with the same internal state, which can be used in separate threads.
50
         */
51
    XsltProcessor * clone();
52

    
53

    
54
     ~XsltProcessor(){
55
        clearProperties();
56
        clearParameters();
57
     }
58

    
59
        //! Get the SaxonProcessor object
60
        /**
61
        * @return SaxonProcessor - Pointer to the object
62
        */
63
    SaxonProcessor * getSaxonProcessor(){return proc;}
64

    
65
    //!set the current working directory
66
    /**
67
      * @param cwd - Current working directory
68
     */
69
   void setcwd(const char* cwd);
70

    
71

    
72
   //!Set the base output URI.
73
       /**
74
        * <p>This defaults to the base URI of the {@link Destination} for the principal output
75
        * of the transformation if a destination is supplied and its base URI is known.</p>
76
        * <p>If a base output URI is supplied using this method then it takes precedence
77
        * over any base URI defined in the supplied {@code Destination} object, and
78
        * it may cause the base URI of the {@code Destination} object to be modified in situ.</p>
79
        * <p> The base output URI is used for resolving relative URIs in the <code>href</code> attribute
80
        * of the <code>xsl:result-document</code> instruction; it is accessible to XSLT stylesheet
81
        * code using the XPath {@code current-output-uri()} function</p>
82
        *
83
        * @param baseUri - the base output URI
84
        */
85
   void setBaseOutputURI(const char * baseURI);
86

    
87

    
88

    
89
    //!Set the source document from an XdmNode for the transformation.
90
     /**
91
        * @param value - The source to the stylesheet as a pointer to the XdmNode object.
92
        */        
93
    void setSourceFromXdmNode(XdmNode * value);
94

    
95
    /**
96
     * Set the source from file for the transformation.
97
    */
98
    void setSourceFromFile(const char * filename);
99

    
100
    /**
101
     * Set the output file of where the transformation result is sent
102
    */
103
    void setOutputFile(const char* outfile);
104

    
105

    
106
    /**
107
    * Say whether just-in-time compilation of template rules should be used.
108
    * @param jit true if just-in-time compilation is to be enabled. With this option enabled,
109
    *            static analysis of a template rule is deferred until the first time that the
110
    *            template is matched. This can improve performance when many template
111
    *            rules are rarely used during the course of a particular transformation; however,
112
    *            it means that static errors in the stylesheet will not necessarily cause the
113
    *            {@link #compile(Source)} method to throw an exception (errors in code that is
114
    *            actually executed will still be notified to the registered <code>ErrorListener</code>
115
    *            or <code>ErrorList</code>, but this may happen after the {@link #compile(Source)}
116
    *            method returns). This option is enabled by default in Saxon-EE, and is not available
117
    *            in Saxon-HE or Saxon-PE.
118
    *            <p><b>Recommendation:</b> disable this option unless you are confident that the
119
    *            stylesheet you are compiling is error-free.</p>
120
    */
121
    void setJustInTimeCompilation(bool jit);
122

    
123
    /**
124
     * Set the value of a stylesheet parameter
125
     *
126
     * @param name  the name of the stylesheet parameter, as a string. For namespaced parameter use the JAXP solution i.e. "{uri}name"
127
     * @param value the value of the stylesheet parameter, or nullptr to clear a previously set value
128
     */
129
    void setParameter(const char* name, XdmValue*value);
130

    
131
    /**
132
     * Get a parameter value by name
133
     * @param name - Specified paramater name to get
134
     * @return XdmValue
135
    */
136
     XdmValue* getParameter(const char* name);
137

    
138

    
139
    /**
140
     * Remove a parameter (name, value) pair from a stylesheet
141
     *
142
     * @param name  the name of the stylesheet parameter
143
     * @return bool - outcome of the romoval
144
     */
145
    bool removeParameter(const char* name);
146

    
147
    /**
148
     * Set a property specific to the processor in use. 
149
     * XsltProcessor: set serialization properties (names start with '!' i.e. name "!method" -> "xml")
150
     * 'o':outfile name, 'it': initial template, 'im': initial mode, 's': source as file name
151
     * 'm': switch on message listener for xsl:message instructions (TODO: this feature should be event based), 'item'| 'node' : source supplied as an XdmNode object
152
     * @param name of the property
153
     * @param value of the property
154
     */
155
    void setProperty(const char* name, const char* value);
156

    
157
    /**
158
     * Get a property value by name
159
     * @param name - Specified paramater name to get
160
     * @return string - Get string of the property as char pointer array
161
    */
162
    const char* getProperty(const char* name);
163

    
164
        //! Get all parameters as a std::map
165
     /**
166
      * 
167
      * Please note that the key name has been prefixed with 'param:', for example 'param:name'
168
      * @return std:map with key as string name mapped to XdmValue. 
169
      * 
170
     */
171
     std::map<std::string,XdmValue*>& getParameters();
172

    
173
        //! Get all properties as a std::map
174
     /**
175
      *  
176
      * @return std:map with key as string name mapped to string values.
177
     */
178
     std::map<std::string,std::string>& getProperties();
179

    
180
    //!Clear parameter values set
181
    /**
182
     * Default behaviour (false) is to leave XdmValues in memory
183
     *  true then XdmValues are deleted
184
     *  @param deleteValues.  Individual pointers to XdmValue objects have to be deleted in the calling program
185
     */
186
    void clearParameters(bool deleteValues=false);
187

    
188
     //! Clear property values set
189
    void clearProperties();
190

    
191
    /**
192
     * This method gives users the option to switch on or off the <code>xsl:message</code> feature. It is also possible
193
     * to send the <code>xsl:message</code> outputs to file given by file name.
194
     * @param show - boolean to indicate if xsl:message should be outputted. Default is on.
195
     * @param  filename - If the filename argument is present then the xsl:message output is appended to the given
196
     *                    filename with location cwd+filename
197
     */
198
    void setupXslMessage(bool show, const char* filename=nullptr);
199

    
200

    
201
      //!Perform a one shot transformation.
202
    /**
203
     * The result is stored in the supplied outputfile.
204
     *
205
     * @param sourcefile - The file name of the source document
206
     * @param stylesheetfile - The file name of the stylesheet document. If nullptr the most recently compiled stylesheet is used
207
     * @param outputfile - The file name where results will be stored
208
     */
209
    void transformFileToFile(const char* sourcefile, const char* stylesheetfile, const char* outputfile); 
210

    
211
        //!Perform a one shot transformation.
212
    /**
213
     * The result is returned as a string
214
     *
215
     * @param sourcefile - The file name of the source document
216
     * @param stylesheetfile - The file name of the stylesheet document. If nullptr the most recently compiled stylesheet is used
217
     * @return char array - result of the transformation
218
     */
219
    const char * transformFileToString(const char* sourcefile, const char* stylesheetfile);
220

    
221
    /**
222
     * Perform a one shot transformation. The result is returned as an XdmValue
223
     *
224
     * @param sourcefile - The file name of the source document
225
     * @param stylesheetfile - The file name of the stylesheet document. If nullptr the most recently compiled stylesheet is used
226
     * @return XdmValue - result of the transformation
227
     */
228
    XdmValue * transformFileToValue(const char* sourcefile, const char* stylesheetfile);
229

    
230

    
231
     //! compile a stylesheet file.
232
    /**
233
     * The compiled stylesheet is cached and available for execution later.
234
     * @param stylesheet  - The file name of the stylesheet document.
235
     */
236
    void compileFromFile(const char* stylesheet);
237

    
238
     //!compile a stylesheet received as a string.
239
    /**
240
     * 
241
     * The compiled stylesheet is cached and available for execution later.
242
     * @param stylesheet as a lexical string representation
243
     */
244
    void compileFromString(const char* stylesheet);
245

    
246

    
247
     //!compile a stylesheet received as a string and save to an exported file (SEF).
248
    /**
249
     * 
250
     * The compiled stylesheet is saved as SEF to file store
251
     * @param stylesheet as a lexical string representation
252
     * @param filename - the file to which the compiled package should be saved
253
     */
254
    void compileFromStringAndSave(const char* stylesheet, const char* filename);
255

    
256

    
257
     //!compile a stylesheet received as a file and save to an exported file (SEF).
258
    /**
259
     * 
260
     * The compiled stylesheet is saved as SEF to file store
261
     * @param xslFilename - file name of the stylesheet
262
     * @param filename - the file to which the compiled package should be saved
263
     */
264
    void compileFromFileAndSave(const char* xslFilename, const char* filename);
265

    
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
     * @param filename - the file to which the compiled package should be saved
272
     */
273
    void compileFromXdmNodeAndSave(XdmNode * node, const char* filename);
274

    
275
     //!compile a stylesheet received as an XdmNode.
276
    /**
277
     * The compiled stylesheet is cached and available for execution later.
278
     * @param stylesheet as a lexical string representation
279
     */
280
    void compileFromXdmNode(XdmNode * node);
281

    
282

    
283
    //! Internal method to release cached stylesheet
284
    /**
285
     *
286
     * @param void
287
     */
288
    void releaseStylesheet();
289

    
290

    
291
    //! Execute transformation to string. Properties supplied in advance.
292
    /**
293
     * Perform the transformation based upon what has been cached.
294
     * @return char*. Pointer to Array of chars. Result returned as a string.
295
     *
296
     */
297
    const char * transformToString();
298

    
299
    //! Execute transformation to Xdm Value. Properties supplied in advance.
300
    /**
301
     * Perform the transformation based upon cached stylesheet and any source document.
302
     * @return as an XdmValue.
303
     *
304
     */
305
    XdmValue * transformToValue();
306

    
307
    //! Execute transformation to file. Properties supplied in advance.
308
    /**
309
     * Perform the transformation based upon cached stylesheet and source document.
310
     * Assume the outputfile has been set in advance
311
     * @return as an XdmValue.
312
     *
313

314
     */
315
    void transformToFile();
316

    
317
    /**
318
     * Checks for pending exceptions without creating a local reference to the exception object
319
     * @return bool - true when there is a pending exception; otherwise return false
320
    */
321
    bool exceptionOccurred();
322

    
323

    
324
    //! Get the SaxonApiException object created when we have an error
325
    /**
326
     * After the execution of the processor if there is an error, then a SaxonApiException is created.
327
     * NULL returned if there is no error.
328
     * @return SaxonApiException object of the exception thrown.
329
     */
330
    SaxonApiException * getException();
331

    
332

    
333
     //! Clear any exception thrown
334
    void exceptionClear();
335

    
336

    
337
    //! Check for exception thrown.
338
    /**
339
    * @return char*. Returns the exception message if thrown otherwise return nullptr
340
    */
341
    const char* checkException();
342

    
343

    
344
     //! Get the ith error message if there are any error
345
    /**
346
     * A transformation may have a number of errors reported against it.
347
     * @return char* - The message of the exception
348
    */
349
    const char * getErrorMessage();
350

    
351
     //! Get the ith error code if there are any error
352
    /**
353
     * A transformation may have a number of errors reported against it.
354
     * @return char* - The error code of the exception. The error code are related to the specific specification
355
    */
356
    const char * getErrorCode();
357

    
358

    
359

    
360
private:
361
        SaxonProcessor* proc;/*!Pointer to the SaxonProcessor */
362
        jclass  cppClass;
363
        jobject cppXT, stylesheetObject;
364
    std::string cwdXT; /*!< current working directory */
365
        bool nodeCreated;
366
        std::map<std::string,XdmValue*> parameters; /*!< map of parameters used for the transformation as (string, value) pairs */
367
        std::map<std::string,std::string> properties; /*!< map of properties used for the transformation as (string, string) pairs */
368
    bool jitCompilation;
369
    SaxonApiException * exception;
370
};
371

    
372

    
373
#endif /* SAXON_XSLT_H */
(43-43/51)