Project

Profile

Help

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

he / latest9.9 / hec / Saxon.C.API / XsltExecutable.h @ 1117bc69

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_XSLTEXEC_H
9
#define SAXON_XSLTEXEC_H
10

    
11

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

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

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

    
28
friend class XsltProcessor;
29

    
30
public:
31

    
32

    
33
     ~XsltExecutable();
34

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

    
44

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

    
60

    
61

    
62
    //!Set the source document from an XdmNode for the transformation.
63
     /**
64
        * @param value - The source to the stylesheet as a pointer to the XdmNode object.
65
        */
66

    
67
    void setGlobalContextItem(XdmItem * value);
68

    
69
    /**
70
     * Set the source from file for the transformation.
71
    */
72
    void setGlobalContextFromFile(const char * filename);
73

    
74

    
75
    //!The initial value to which templates are to be applied (equivalent to the <code>select</code> attribute of <code>xsl:apply-templates</code>)
76
    /**
77
    *  @param selection - The value to which the templates are to be applied
78
    */
79
    void setInitialMatchSelection(XdmValue * selection);
80

    
81
        //!The initial filename to which templates are to be applied (equivalent to the <code>select</code> attribute of <code>xsl:apply-templates</code>).
82
        /**
83
        * The file is parsed internall
84
        *  @param filename - The file name to which the templates are to be applied
85
        */
86
    void setInitialMatchSelectionAsFile(const char * filename);
87

    
88
    /**
89
     * Set the output file of where the transformation result is sent
90
    */
91
    void setOutputFile(const char* outfile);
92

    
93

    
94

    
95

    
96
    /**
97
    *Set true if the return type of callTemplate, applyTemplates and transform methods is to return XdmValue,
98
    *otherwise return XdmNode object with root Document node
99
    * @param option true if return raw result, i.e. XdmValue, otherwise return XdmNode
100
    *
101
    */
102
    void setResultAsRawValue(bool option);
103

    
104
    /**
105
     * Set the value of a stylesheet parameter
106
     *
107
     * @param name  the name of the stylesheet parameter, as a string. For namespaced parameter use the JAXP solution i.e. "{uri}name"
108
     * @param value the value of the stylesheet parameter, or null to clear a previously set value
109
     * @param _static For static (compile-time) parameters we set this flag to true, which means the parameter is
110
     * must be set on the XsltCompiler object, prior to stylesheet compilation. The default is false. Non-static parameters
111
     * may also be provided.
112
     */
113
    void setParameter(const char* name, XdmValue*value);
114

    
115

    
116

    
117
    /**
118
     * Get a parameter value by name
119
     * @param name - Specified paramater name to get
120
     * @return XdmValue
121
    */
122
     XdmValue* getParameter(const char* name);
123

    
124

    
125
    /**
126
     * Remove a parameter (name, value) pair from a stylesheet
127
     *
128
     * @param name  the name of the stylesheet parameter
129
     * @return bool - outcome of the romoval
130
     */
131
    bool removeParameter(const char* name);
132

    
133
    /**
134
     * Set a property specific to the processor in use.
135
     * XsltProcessor: set serialization properties (names start with '!' i.e. name "!method" -> "xml")
136
     * 'o':outfile name, 'it': initial template, 'im': initial mode, 's': source as file name
137
     * 'm': switch on message listener for xsl:message instructions
138
     * @param name of the property
139
     * @param value of the property
140
     */
141
    void setProperty(const char* name, const char* value);
142

    
143

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

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

    
173
    /**
174
     * Get a property value by name
175
     * @param name - Specified paramater name to get
176
     * @return string - Get string of the property as char pointer array
177
    */
178
    const char* getProperty(const char* name);
179

    
180
        //! Get all parameters as a std::map
181
     /**
182
      *
183
      * Please note that the key name has been prefixed with 'param:', for example 'param:name'
184
      * @return std:map with key as string name mapped to XdmValue.
185
      *
186
     */
187
     std::map<std::string,XdmValue*>& getParameters();
188

    
189
        //! Get all properties as a std::map
190
     /**
191
      *
192
      * @return std:map with key as string name mapped to string values.
193
     */
194
     std::map<std::string,std::string>& getProperties();
195

    
196
    //!Clear parameter values set
197
    /**
198
     * Default behaviour (false) is to leave XdmValues in memory
199
     *  true then XdmValues are deleted
200
     *  @param deleteValues.  Individual pointers to XdmValue objects have to be deleted in the calling program
201
     */
202
    void clearParameters(bool deleteValues=false);
203

    
204
     //! Clear property values set
205
    void clearProperties();
206

    
207
    /**
208
    * Utility method for working with Saxon/C on Python
209
    */
210
    XdmValue ** createXdmValueArray(int len){
211
        return (new XdmValue*[len]);
212
    }
213

    
214
    /**
215
    * Utility method for working with Saxon/C on Python
216
    */
217
    char** createCharArray(int len){
218
        return (new char*[len]);
219
    }
220

    
221
    void deleteXdmValueArray(XdmValue ** arr, int len){
222
        for(int i =0; i< len; i++) {
223
                //delete arr[i];
224
        }
225
        delete [] arr;
226
    }
227

    
228
    /**
229
     * This method gives users the option to switch on or off the <code>xsl:message</code> feature. It is also possible
230
     * to send the <code>xsl:message</code> outputs to file given by file name.
231
     * @param show - boolean to indicate if xsl:message should be outputted. Default is on.
232
     * @param  filename - If the filename argument is present then the xsl:message output is appended to the given
233
     *                    filename with location cwd+filename
234
     */
235
    void setupXslMessage(bool show, const char* filename=NULL);
236

    
237

    
238
    /**
239
     * Produce a representation of the compiled stylesheet, in XML form, suitable for
240
     * distribution and reloading. If the configuration under which the export takes place
241
     * is suitably licensed, then license information will be included in the export file
242
     * allowing execution of the stylesheet without any additional license.
243
     * <p><i>The detailed form of the output representation is not documented.</i></p>
244
     *
245
     * @param outputFilename the destination for the XML document containing the diagnostic representation
246
     *                    of the compiled stylesheet. The stream will be closed when writing has finished.
247
     */
248
    void export(const char * filename);
249

    
250

    
251
      //!Perform a one shot transformation.
252
    /**
253
     * The result is stored in the supplied outputfile.
254
     *
255
     * @param sourcefile - The file name of the source document
256
     * @param outputfile - The file name where results will be stored
257
     */
258
    void transformFileToFile(const char* sourcefile, const char* outputfile);
259

    
260
        //!Perform a one shot transformation.
261
    /**
262
     * The result is returned as a string
263
     *
264
     * @param sourcefile - The file name of the source document
265
     * @return char array - result of the transformation
266
     */
267
    const char * transformFileToString(const char* sourcefile);
268

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

    
277

    
278

    
279
     //!Invoke the stylesheet by applying templates to a supplied input sequence, Saving the results to file.
280
    /**
281
     * The initial match selection must be set using one of the two methods setInitialMatchSelection or setInitialMatchSelectionFile.
282
     * The result is stored in the supplied output file.
283
     *
284
     * @param outputfile - The file name where results will be stored
285
     */
286
    void applyTemplatesReturningFile(const char* outfile);
287

    
288
     //!Invoke the compiled stylesheet by applying templates to a supplied input sequence, Saving the results as serialized string.
289
    /**
290
     * The initial match selection must be set using one of the two methods setInitialMatchSelection or setInitialMatchSelectionFile.
291
     *
292
     */
293
    const char* applyTemplatesReturningString();
294

    
295
     //!Invoke the compiled stylesheet by applying templates to a supplied input sequence, Saving the results as an XdmValue.
296
    /**
297
     * The initial match selection must be set using one of the two methods setInitialMatchSelection or setInitialMatchSelectionFile.
298
     *
299
     */
300
    XdmValue * applyTemplatesReturningValue();
301

    
302
    //! Invoke a transformation by calling a named template and save result to file.
303
    /** The results of calling the template are wrapped in a document node, which is then sent to the specified
304
    * file destination. If setInitialTemplateParameters(std::Map, boolean) has been
305
    * called, then the parameters supplied are made available to the called template (no error
306
    * occurs if parameters are supplied that are not used).
307
    * @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 null, the clark name for xsl:initial-template is used.
308
    * @param outputfile - The file name where results will be stored,
309
    */
310
    void callTemplateReturningFile(const char* templateName, const char* outfile);
311

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

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

    
332

    
333

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

    
345

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

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

    
368

    
369

    
370

    
371
    //! Execute transformation to string. Properties supplied in advance.
372
    /**
373
     * Perform the transformation based upon what has been cached.
374
     * @param source - source document suppplied as an XdmNode object
375
     * @return char*. Pointer to Array of chars. Result returned as a string.
376
     *
377
     */
378
    const char * transformToString(XdmNode * source);
379

    
380
    //! Execute transformation to Xdm Value. Properties supplied in advance.
381
    /**
382
     * Perform the transformation based upon cached stylesheet and any source document.
383
     * @param source - source document suppplied as an XdmNode object
384
     * @return as an XdmValue.
385
     *
386
     */
387
    XdmValue * transformToValue(XdmNode * source);
388

    
389
    //! Execute transformation to file. Properties supplied in advance.
390
    /**
391
     * Perform the transformation based upon cached stylesheet and source document.
392
     * Assume the outputfile has been set in advance
393
     * @param source - source document suppplied as an XdmNode object
394
     * @return as an XdmValue.
395
     *
396

397
     */
398
    void transformToFile(XdmNode * source);
399

    
400
    /**
401
     * Checks for pending exceptions without creating a local reference to the exception object
402
     * @return bool - true when there is a pending exception; otherwise return false
403
    */
404
    bool exceptionOccurred();
405

    
406

    
407
     //! Check for exception thrown.
408
        /**
409
        * @return cha*. Returns the exception message if thrown otherwise return NULL
410
        */
411
    const char* checkException();
412

    
413

    
414
     //! Clear any exception thrown
415
    void exceptionClear();
416

    
417
     //!Get number of errors reported during execution or evaluate of stylesheet
418
    /**
419
     * A transformation may have a number of errors reported against it.
420
     * @return int - Count of the exceptions recorded against the transformation
421
    */
422
    int exceptionCount();
423

    
424
     //! Get the ith error message if there are any error
425
    /**
426
     * A transformation may have a number of errors reported against it.
427
     * @return char* - The message of the i'th exception
428
    */
429
    const char * getErrorMessage(int i);
430

    
431
     //! Get the ith error code if there are any error
432
    /**
433
     * A transformation may have a number of errors reported against it.
434
     * @return char* - The error code of the i'th exception. The error code are related to the specific specification
435
    */
436
    const char * getErrorCode(int i);
437

    
438

    
439

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

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

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

    
460

    
461
    jclass  cppClass;
462
        jobject executableObject, selection;
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_XSLT30_H */
(35-35/50)