Project

Profile

Help

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

he / src / main / c / Saxon.C.API / XsltExecutable.h @ 7728ae0b

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_EXEC_H
9
#define SAXON_XSLT_EXEC_H
10

    
11

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

    
16
class SaxonProcessor;
17
class SaxonApiException;
18
class Xslt30Processor;
19
class XdmValue;
20
class XdmItem;
21
class XdmNode;
22
class XdmFunctionItem;
23
class XdmMap;
24
class XdmArray;
25

    
26
/*! An <code>XsltExecutable</code> represents the compiled form of a stylesheet.
27
 * <p>An XsltExecutable is created by using one of the <code>compile</code> methods on the
28
  * {@link XsltProcessor} class.</p>
29
 */
30
class XsltExecutable {
31

    
32
friend class Xslt30Processor;
33

    
34

    
35
public:
36

    
37

    
38
     ~XsltExecutable();
39

    
40
    //!set the current working directory (cwd). This method also applies to the
41
    // static base URI for XSLT stylesheets when supplied as lexical string.
42
    /**
43
      * The cwd is used to set the base URI is part of the static context, and is used to resolve
44
      * any relative URIs appearing within XSLT.
45
      * @param cwd - Current working directory
46
     */
47
   void setcwd(const char* cwd);
48

    
49

    
50
      //!Set the base output URI.
51
          /**
52
           * <p>This defaults to the base URI of the {@link Destination} for the principal output
53
           * of the transformation if a destination is supplied and its base URI is known.</p>
54
           * <p>If a base output URI is supplied using this method then it takes precedence
55
           * over any base URI defined in the supplied {@code Destination} object, and
56
           * it may cause the base URI of the {@code Destination} object to be modified in situ.</p>
57
           * <p> The base output URI is used for resolving relative URIs in the <code>href</code> attribute
58
           * of the <code>xsl:result-document</code> instruction; it is accessible to XSLT stylesheet
59
           * code using the XPath {@code current-output-uri()} function</p>
60
           *
61
           * @param baseUri - the base output URI
62
           */
63
      void setBaseOutputURI(const char * baseURI);
64

    
65

    
66

    
67
    //!Set the source document from an XdmNode for the transformation.
68
     /**
69
        * @param value - The source to the stylesheet as a pointer to the XdmNode object.
70
        */
71

    
72
    void setGlobalContextItem(XdmItem * value);
73

    
74
    /**
75
     * Set the source from file for the transformation.
76
    */
77
    void setGlobalContextFromFile(const char * filename);
78

    
79

    
80
    //! Create a clone object of this Xslt30Processor object
81
    /**
82
     *
83
     * @return
84
     */
85
    XsltExecutable *clone();
86

    
87

    
88
    //!The initial value to which templates are to be applied (equivalent to the <code>select</code> attribute of <code>xsl:apply-templates</code>)
89
    /**
90
    *  @param selection - The value to which the templates are to be applied
91
    */
92
    void setInitialMatchSelection(XdmValue * selection);
93

    
94
        //!The initial filename to which templates are to be applied (equivalent to the <code>select</code> attribute of <code>xsl:apply-templates</code>).
95
        /**
96
        * The file is parsed internall
97
        *  @param filename - The file name to which the templates are to be applied
98
        */
99
    void setInitialMatchSelectionAsFile(const char * filename);
100

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

    
106

    
107

    
108

    
109
    /**
110
    *Set true if the return type of callTemplate, applyTemplates and transform methods is to return XdmValue,
111
    *otherwise return XdmNode object with root Document node
112
    * @param option true if return raw result, i.e. XdmValue, otherwise return XdmNode
113
    *
114
    */
115
    void setResultAsRawValue(bool option);
116

    
117
    /**
118
     * Set the value of a stylesheet parameter
119
     *
120
     * @param name  the name of the stylesheet parameter, as a string. For namespaced parameter use the JAXP solution i.e. "{uri}name"
121
     * @param value the value of the stylesheet parameter, or nullptr to clear a previously set value
122
     */
123
    void setParameter(const char* name, XdmValue * value);
124

    
125

    
126

    
127
    /**
128
     * Get a parameter value by name
129
     * @param name - Specified paramater name to get
130
     * @return XdmValue
131
    */
132
     XdmValue* getParameter(const char* name);
133

    
134

    
135
    /**
136
     * Remove a parameter (name, value) pair from a stylesheet
137
     *
138
     * @param name  the name of the stylesheet parameter
139
     * @return bool - outcome of the romoval
140
     */
141
    bool removeParameter(const char* name);
142

    
143
    /**
144
     * Set a property specific to the processor in use.
145
     * XsltProcessor: set serialization properties (names start with '!' i.e. name "!method" -> "xml")
146
     * 'o':outfile name, 'it': initial template, 'im': initial mode, 's': source as file name
147
     * 'm': switch on message listener for xsl:message instructions
148
     * @param name of the property
149
     * @param value of the property
150
     */
151
    void setProperty(const char* name, const char* value);
152

    
153

    
154
    /**
155
     * Set parameters to be passed to the initial template. These are used
156
     * whether the transformation is invoked by applying templates to an initial source item,
157
     * or by invoking a named template. The parameters in question are the xsl:param elements
158
     * appearing as children of the xsl:template element.
159
     * <p>The parameters are supplied in the form of a map; the key is a QName given as a string which must
160
     * match the name of the parameter; the associated value is an XdmValue containing the
161
     * value to be used for the parameter. If the initial template defines any required
162
     * parameters, the map must include a corresponding value. If the initial template defines
163
     * any parameters that are not present in the map, the default value is used. If the map
164
     * contains any parameters that are not defined in the initial template, these values
165
     * are silently ignored.</p>
166
     * <p>The supplied values are converted to the required type using the function conversion
167
     * rules. If conversion is not possible, a run-time error occurs (not now, but later, when
168
     * the transformation is actually run).</p>
169
     * <p>The <code>XsltTransformer</code> retains a reference to the supplied map, so parameters can be added or
170
     * changed until the point where the transformation is run.</p>
171
     * <p>The XSLT 3.0 specification makes provision for supplying parameters to the initial
172
     * template, as well as global stylesheet parameters. Although there is no similar provision
173
     * in the XSLT 1.0 or 2.0 specifications, this method works for all stylesheets, regardless whether
174
     * XSLT 3.0 is enabled or not.</p>
175
     *
176
     * @param parameters the parameters to be used for the initial template
177
     * @param tunnel     true if these values are to be used for setting tunnel parameters;
178
     *                   false if they are to be used for non-tunnel parameters
179
     */
180

    
181
    void setInitialTemplateParameters(std::map<std::string,XdmValue*> parameters, bool tunnel);
182

    
183
    /**
184
     * Get a property value by name
185
     * @param name - Specified paramater name to get
186
     * @return string - Get string of the property as char pointer array
187
    */
188
    const char* getProperty(const char* name);
189

    
190
        //! Get all parameters as a std::map
191
     /**
192
      *
193
      * Please note that the key name has been prefixed with 'param:', for example 'param:name'
194
      * @return std:map with key as string name mapped to XdmValue.
195
      *
196
     */
197
     std::map<std::string,XdmValue*>& getParameters();
198

    
199
        //! Get all properties as a std::map
200
     /**
201
      *
202
      * @return std:map with key as string name mapped to string values.
203
     */
204
     std::map<std::string,std::string>& getProperties();
205

    
206
    //!Clear parameter values set
207
    /**
208
     * Default behaviour (false) is to leave XdmValues in memory
209
     *  true then XdmValues are deleted
210
     *  @param deleteValues.  Individual pointers to XdmValue objects have to be deleted in the calling program
211
     */
212
    void clearParameters(bool deleteValues=false);
213

    
214
     //! Clear property values set
215
    void clearProperties();
216

    
217
    /**
218
    * Utility method for working with Saxon/C on Python
219
    */
220
    XdmValue ** createXdmValueArray(int len){
221
        return (new XdmValue*[len]);
222
    }
223

    
224
    /**
225
    * Utility method for working with Saxon/C on Python
226
    */
227
    char** createCharArray(int len){
228
        return (new char*[len]);
229
    }
230

    
231
    void deleteXdmValueArray(XdmValue ** arr, int len){
232
        for(int i =0; i< len; i++) {
233
                //delete arr[i];
234
        }
235
        delete [] arr;
236
    }
237

    
238
    /**
239
     * This method gives users the option to switch on or off the <code>xsl:message</code> feature. It is also possible
240
     * to send the <code>xsl:message</code> outputs to file given by file name.
241
     * @param show - boolean to indicate if xsl:message should be outputted. Default is on.
242
     * @param  filename - If the filename argument is present then the xsl:message output is appended to the given
243
     *                    filename with location cwd+filename
244
     */
245
    void setupXslMessage(bool show, const char* filename=nullptr);
246

    
247

    
248

    
249
    /**
250
    * Get the messages written using the <code>xsl:message</code> instruction
251
    * @return XdmValue - Messages returned as a sequence of XdmNode objects within an XdmValue object.
252
    */
253
    XdmValue * getXslMessages();
254

    
255

    
256
    /**
257
     * Produce a representation of the compiled stylesheet, in XML form, suitable for
258
     * distribution and reloading. If the configuration under which the export takes place
259
     * is suitably licensed, then license information will be included in the export file
260
     * allowing execution of the stylesheet without any additional license.
261
     * <p><i>The detailed form of the output representation is not documented.</i></p>
262
     *
263
     * @param outputFilename the destination for the XML document containing the diagnostic representation
264
     *                    of the compiled stylesheet. The stream will be closed when writing has finished.
265
     */
266
    void exportStylesheet(const char * filename);
267

    
268

    
269
      //!Perform a one shot transformation.
270
    /**
271
     * The result is stored in the supplied outputfile.
272
     *
273
     * @param sourcefile - The file name of the source document
274
     * @param outputfile - The file name where results will be stored
275
     */
276
    void transformFileToFile(const char* sourcefile, const char* outputfile);
277

    
278
        //!Perform a one shot transformation.
279
    /**
280
     * The result is returned as a string
281
     *
282
     * @param sourcefile - The file name of the source document
283
     * @return char array - result of the transformation
284
     */
285
    const char * transformFileToString(const char* sourcefile);
286

    
287
    /**
288
     * Perform a one shot transformation. The result is returned as an XdmValue
289
     *
290
     * @param sourcefile - The file name of the source document
291
     * @return XdmValue - result of the transformation
292
     */
293
    XdmValue * transformFileToValue(const char* sourcefile);
294

    
295

    
296

    
297
     //!Invoke the stylesheet by applying templates to a supplied input sequence, Saving the results to file.
298
    /**
299
     * The initial match selection must be set using one of the two methods setInitialMatchSelection or setInitialMatchSelectionFile.
300
     * The result is stored in the supplied output file.
301
     *
302
     * @param outputfile - The file name where results will be stored
303
     */
304
    void applyTemplatesReturningFile(const char* outfile);
305

    
306
     //!Invoke the compiled stylesheet by applying templates to a supplied input sequence, Saving the results as serialized string.
307
    /**
308
     * The initial match selection must be set using one of the two methods setInitialMatchSelection or setInitialMatchSelectionFile.
309
     *
310
     */
311
    const char* applyTemplatesReturningString();
312

    
313
     //!Invoke the compiled stylesheet by applying templates to a supplied input sequence, Saving the results as an XdmValue.
314
    /**
315
     * The initial match selection must be set using one of the two methods setInitialMatchSelection or setInitialMatchSelectionFile.
316
     *
317
     */
318
    XdmValue * applyTemplatesReturningValue();
319

    
320
    //! Invoke a transformation by calling a named template and save result to file.
321
    /** The results of calling the template are wrapped in a document node, which is then sent to the specified
322
    * file destination. If setInitialTemplateParameters(std::Map, boolean) has been
323
    * called, then the parameters supplied are made available to the called template (no error
324
    * occurs if parameters are supplied that are not used).
325
    * @param templateName - The name of the initial template. This must match the name of a public named template in the stylesheet. If the value is nullptr, the clark name for xsl:initial-template is used.
326
    * @param outputfile - The file name where results will be stored,
327
    */
328
    void callTemplateReturningFile(const char* templateName, const char* outfile);
329

    
330
    //! Invoke a transformation by calling a named template and return result as a string.
331
    /** The results of calling the template are wrapped in a document node, which is then serialized as a string.
332
    * If setInitialTemplateParameters(std::Map, boolean) has been
333
    * called, then the parameters supplied are made available to the called template (no error
334
    * occurs if parameters are supplied that are not used).
335
    * @param templateName - the name of the initial template. This must match the name of a public named template in the stylesheet. If the value is nullptr, the clark name for xsl:initial-template is used.
336
    * @param outputfile - The file name where results will be stored,
337
    */
338
    const char* callTemplateReturningString(const char* templateName);
339

    
340
    //! Invoke a transformation by calling a named template and return result as a string.
341
    /** The results of calling the template are wrapped in a document node, which is then returned as an XdmValue.
342
    * If setInitialTemplateParameters(std::Map, boolean) has been
343
    * called, then the parameters supplied are made available to the called template (no error
344
    * occurs if parameters are supplied that are not used).
345
    * @param templateName - the name of the initial template. This must match the name of a public named template in the stylesheet. If the value is nullptr, the clark name for xsl:initial-template is used.
346
    * @param outputfile - The file name where results will be stored,
347
    */
348
    XdmValue* callTemplateReturningValue(const char* templateName);
349

    
350

    
351

    
352
    //! Call a public user-defined function in the already compiled stylesheet
353
    /** Here we wrap the result in an XML document, and sending this document to a specified file
354
    * @param functionName - The name of the function to be called
355
    * @param arguments - Pointer array of XdmValue object - he values of the arguments to be supplied to the function. These
356
    *                    will be converted if necessary to the type as defined in the function signature, using
357
    *                    the function conversion rules.
358
    * @param argument_length - the Coutn of arguments objects in the array
359
    * @param outputfile - The file name where results will be stored,
360
    */
361
    void callFunctionReturningFile(const char* functionName, XdmValue ** arguments, int argument_length, const char* outfile);
362

    
363

    
364
    //! Call a public user-defined function in the compiled stylesheet
365
    /** Here we wrap the result in an XML document, and serialized this document to string value
366
    * @param functionName - The name of the function to be called
367
    * @param arguments - Pointer array of XdmValue object - he values of the arguments to be supplied to the function. These
368
    *                    will be converted if necessary to the type as defined in the function signature, using
369
    *                    the function conversion rules.
370
    * @param argument_length - the Coutn of arguments objects in the array
371
    * @param outputfile - The file name where results will be stored,
372
    */
373
    const char * callFunctionReturningString(const char* functionName, XdmValue ** arguments, int argument_length);
374

    
375
    //! Call a public user-defined function in the already compiled stylesheet
376
    /** Here we wrap the result in an XML document, and return the document as an XdmValue
377
    * @param functionName - The name of the function to be called
378
    * @param arguments - Pointer array of XdmValue object - he values of the arguments to be supplied to the function. These
379
    *                    will be converted if necessary to the type as defined in the function signature, using
380
    *                    the function conversion rules.
381
    * @param argument_length - the Coutn of arguments objects in the array
382
    * @param outputfile - The file name where results will be stored,
383
    */
384
    XdmValue * callFunctionReturningValue(const char* functionName, XdmValue ** arguments, int argument_length);
385

    
386

    
387

    
388

    
389
    //! Execute transformation to string. Properties supplied in advance.
390
    /**
391
     * Perform the transformation based upon what has been cached.
392
     * @param source - source document suppplied as an XdmNode object
393
     * @return char*. Pointer to Array of chars. Result returned as a string.
394
     *
395
     */
396
    const char * transformToString(XdmNode * source);
397

    
398
    //! Execute transformation to Xdm Value. Properties supplied in advance.
399
    /**
400
     * Perform the transformation based upon cached stylesheet and any source document.
401
     * @param source - source document suppplied as an XdmNode object
402
     * @return as an XdmValue.
403
     *
404
     */
405
    XdmValue * transformToValue(XdmNode * source);
406

    
407
    //! Execute transformation to file. Properties supplied in advance.
408
    /**
409
     * Perform the transformation based upon cached stylesheet and source document.
410
     * Assume the outputfile has been set in advance
411
     * @param source - source document suppplied as an XdmNode object
412
     * @return as an XdmValue.
413
     *
414

415
     */
416
    void transformToFile(XdmNode * source);
417

    
418
    /**
419
     * Checks for pending exceptions without creating a local reference to the exception object
420
     * @return bool - true when there is a pending exception; otherwise return false
421
    */
422
    bool exceptionOccurred();
423

    
424

    
425

    
426

    
427
    //! Check for exception thrown and return the SaxonApiException object.
428
    /**
429
    * @return SaxonApiException. Returns the exception message if thrown otherwise return nullptr
430
    */
431
    SaxonApiException* getException();
432

    
433

    
434
     //! Clear any exception thrown
435
    void exceptionClear();
436

    
437

    
438

    
439
private:
440
 //! Default constructor.
441
    /*!
442
      Creates a XsltExecutable
443
    */
444
    XsltExecutable();
445

    
446
    //! Constructor with the SaxonProcessor supplied.
447
    /*!
448
      @param proc - Supplied pointer to the SaxonProcessor object
449
      cwd - The current working directory
450
    */
451
    XsltExecutable(jobject exObject, std::string cwd="");
452

    
453
        /**
454
         * Xslt30Processor copy constructor.
455
         * @param other - Xslt30Processor
456
         */
457
    XsltExecutable(const XsltExecutable &other);
458

    
459

    
460
    jclass  cppClass;
461
    jclass messageListenerClass;
462
        jobject executableObject, selection, saxonMessageListenerObj;
463
        XdmValue * selectionV;
464
    std::string cwdXE; /*!< current working directory */
465
        bool tunnel, jitCompilation;
466
        std::map<std::string,XdmValue*> parameters; /*!< map of parameters used for the transformation as (string, value) pairs */
467

    
468
        std::map<std::string,std::string> properties; /*!< map of properties used for the transformation as (string, string) pairs */
469

    
470
};
471

    
472

    
473
#endif /* SAXON_XSLT_EXEC_H */
(41-41/56)