Project

Profile

Help

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

he / latest10 / hec / Saxon.C.API / XsltExecutable.h @ 6304fb8b

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 XsltProcessor;
33

    
34
public:
35

    
36

    
37
     ~XsltExecutable();
38

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

    
48

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

    
64

    
65

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

    
71
    void setGlobalContextItem(XdmItem * value);
72

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

    
78

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

    
86

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

    
93
        //!The initial filename to which templates are to be applied (equivalent to the <code>select</code> attribute of <code>xsl:apply-templates</code>).
94
        /**
95
        * The file is parsed internall
96
        *  @param filename - The file name to which the templates are to be applied
97
        */
98
    void setInitialMatchSelectionAsFile(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

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

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

    
124

    
125

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

    
133

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

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

    
152

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

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

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

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

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

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

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

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

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

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

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

    
246

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

    
259

    
260
      //!Perform a one shot transformation.
261
    /**
262
     * The result is stored in the supplied outputfile.
263
     *
264
     * @param sourcefile - The file name of the source document
265
     * @param outputfile - The file name where results will be stored
266
     */
267
    void transformFileToFile(const char* sourcefile, const char* outputfile);
268

    
269
        //!Perform a one shot transformation.
270
    /**
271
     * The result is returned as a string
272
     *
273
     * @param sourcefile - The file name of the source document
274
     * @return char array - result of the transformation
275
     */
276
    const char * transformFileToString(const char* sourcefile);
277

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

    
286

    
287

    
288
     //!Invoke the stylesheet by applying templates to a supplied input sequence, Saving the results to file.
289
    /**
290
     * The initial match selection must be set using one of the two methods setInitialMatchSelection or setInitialMatchSelectionFile.
291
     * The result is stored in the supplied output file.
292
     *
293
     * @param outputfile - The file name where results will be stored
294
     */
295
    void applyTemplatesReturningFile(const char* outfile);
296

    
297
     //!Invoke the compiled stylesheet by applying templates to a supplied input sequence, Saving the results as serialized string.
298
    /**
299
     * The initial match selection must be set using one of the two methods setInitialMatchSelection or setInitialMatchSelectionFile.
300
     *
301
     */
302
    const char* applyTemplatesReturningString();
303

    
304
     //!Invoke the compiled stylesheet by applying templates to a supplied input sequence, Saving the results as an XdmValue.
305
    /**
306
     * The initial match selection must be set using one of the two methods setInitialMatchSelection or setInitialMatchSelectionFile.
307
     *
308
     */
309
    XdmValue * applyTemplatesReturningValue();
310

    
311
    //! Invoke a transformation by calling a named template and save result to file.
312
    /** The results of calling the template are wrapped in a document node, which is then sent to the specified
313
    * file destination. If setInitialTemplateParameters(std::Map, boolean) has been
314
    * called, then the parameters supplied are made available to the called template (no error
315
    * occurs if parameters are supplied that are not used).
316
    * @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.
317
    * @param outputfile - The file name where results will be stored,
318
    */
319
    void callTemplateReturningFile(const char* templateName, const char* outfile);
320

    
321
    //! Invoke a transformation by calling a named template and return result as a string.
322
    /** The results of calling the template are wrapped in a document node, which is then serialized as a string.
323
    * If setInitialTemplateParameters(std::Map, boolean) has been
324
    * called, then the parameters supplied are made available to the called template (no error
325
    * occurs if parameters are supplied that are not used).
326
    * @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.
327
    * @param outputfile - The file name where results will be stored,
328
    */
329
    const char* callTemplateReturningString(const char* templateName);
330

    
331
    //! Invoke a transformation by calling a named template and return result as a string.
332
    /** The results of calling the template are wrapped in a document node, which is then returned as an XdmValue.
333
    * If setInitialTemplateParameters(std::Map, boolean) has been
334
    * called, then the parameters supplied are made available to the called template (no error
335
    * occurs if parameters are supplied that are not used).
336
    * @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.
337
    * @param outputfile - The file name where results will be stored,
338
    */
339
    XdmValue* callTemplateReturningValue(const char* templateName);
340

    
341

    
342

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

    
354

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

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

    
377

    
378

    
379

    
380
    //! Execute transformation to string. Properties supplied in advance.
381
    /**
382
     * Perform the transformation based upon what has been cached.
383
     * @param source - source document suppplied as an XdmNode object
384
     * @return char*. Pointer to Array of chars. Result returned as a string.
385
     *
386
     */
387
    const char * transformToString(XdmNode * source);
388

    
389
    //! Execute transformation to Xdm Value. Properties supplied in advance.
390
    /**
391
     * Perform the transformation based upon cached stylesheet and any source document.
392
     * @param source - source document suppplied as an XdmNode object
393
     * @return as an XdmValue.
394
     *
395
     */
396
    XdmValue * transformToValue(XdmNode * source);
397

    
398
    //! Execute transformation to file. Properties supplied in advance.
399
    /**
400
     * Perform the transformation based upon cached stylesheet and source document.
401
     * Assume the outputfile has been set in advance
402
     * @param source - source document suppplied as an XdmNode object
403
     * @return as an XdmValue.
404
     *
405

406
     */
407
    void transformToFile(XdmNode * source);
408

    
409
    /**
410
     * Checks for pending exceptions without creating a local reference to the exception object
411
     * @return bool - true when there is a pending exception; otherwise return false
412
    */
413
    bool exceptionOccurred();
414

    
415

    
416

    
417

    
418
    //! Check for exception thrown.
419
    /**
420
    * @return cha*. Returns the exception message if thrown otherwise return nullptr
421
    */
422
    SaxonApiException* getException();
423

    
424

    
425
     //! Clear any exception thrown
426
    void exceptionClear();
427

    
428
     //!Get number of errors reported during execution or evaluate of stylesheet
429
    /**
430
     * A transformation may have a number of errors reported against it.
431
     * @return int - Count of the exceptions recorded against the transformation
432
    */
433
    //int exceptionCount();
434

    
435
     //! Get the ith error message if there are any error
436
    /**
437
     * A transformation may have a number of errors reported against it.
438
     * @return char* - The message of the i'th exception
439
    */
440
    const char * getErrorMessage();
441

    
442
     //! Get the ith error code if there are any error
443
    /**
444
     * A transformation may have a number of errors reported against it.
445
     * @return char* - The error code of the i'th exception. The error code are related to the specific specification
446
    */
447
    const char * getErrorCode();
448

    
449

    
450

    
451
private:
452
 //! Default constructor.
453
    /*!
454
      Creates a XsltExecutable
455
    */
456
    XsltExecutable();
457

    
458
    //! Constructor with the SaxonProcessor supplied.
459
    /*!
460
      @param proc - Supplied pointer to the SaxonProcessor object
461
      cwd - The current working directory
462
    */
463
    XsltExecutable(jobject exObject, std::string cwd="");
464

    
465
        /**
466
         * Xslt30Processor copy constructor.
467
         * @param other - Xslt30Processor
468
         */
469
    XsltExecutable(const XsltExecutable &other);
470

    
471

    
472
    jclass  cppClass;
473
        jobject executableObject, selection;
474
        XdmValue * selectionV;
475
    std::string cwdXE; /*!< current working directory */
476
        bool tunnel, jitCompilation;
477
        std::map<std::string,XdmValue*> parameters; /*!< map of parameters used for the transformation as (string, value) pairs */
478

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

    
481
};
482

    
483

    
484
#endif /* SAXON_XSLT_EXEC_H */
(34-34/49)