Project

Profile

Help

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

he / latest10 / hec / Saxon.C.API / XsltExecutable.h @ c1cc9bd8

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

    
254

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

    
267

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

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

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

    
294

    
295

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

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

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

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

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

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

    
349

    
350

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

    
362

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

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

    
385

    
386

    
387

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

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

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

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

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

    
423

    
424

    
425

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

    
432

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

    
436
     //!Get number of errors reported during execution or evaluate of stylesheet
437
    /**
438
     * A transformation may have a number of errors reported against it.
439
     * @return int - Count of the exceptions recorded against the transformation
440
    */
441
    //int exceptionCount();
442

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

    
450
     //! Get the ith error code if there are any error
451
    /**
452
     * A transformation may have a number of errors reported against it.
453
     * @return char* - The error code of the i'th exception. The error code are related to the specific specification
454
    */
455
    const char * getErrorCode();
456

    
457

    
458

    
459
private:
460
 //! Default constructor.
461
    /*!
462
      Creates a XsltExecutable
463
    */
464
    XsltExecutable();
465

    
466
    //! Constructor with the SaxonProcessor supplied.
467
    /*!
468
      @param proc - Supplied pointer to the SaxonProcessor object
469
      cwd - The current working directory
470
    */
471
    XsltExecutable(jobject exObject, std::string cwd="");
472

    
473
        /**
474
         * Xslt30Processor copy constructor.
475
         * @param other - Xslt30Processor
476
         */
477
    XsltExecutable(const XsltExecutable &other);
478

    
479

    
480
    jclass  cppClass;
481
    jclass messageListenerClass;
482
        jobject executableObject, selection, saxonMessageListenerObj;
483
        XdmValue * selectionV;
484
    std::string cwdXE; /*!< current working directory */
485
        bool tunnel, jitCompilation;
486
        std::map<std::string,XdmValue*> parameters; /*!< map of parameters used for the transformation as (string, value) pairs */
487

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

    
490
};
491

    
492

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