Project

Profile

Help

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

he / latest9.9 / hec / Saxon.C.API / XsltExecutable.h @ 5401a5ae

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 SaxonApiException;
18
class Xslt30Processor;
19
class XdmValue;
20
class XdmItem;
21
class XdmNode;
22

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

    
29
friend class XsltProcessor;
30

    
31
public:
32

    
33

    
34
     ~XsltExecutable();
35

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

    
45

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

    
61

    
62

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

    
68
    void setGlobalContextItem(XdmItem * value);
69

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

    
75

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

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

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

    
94

    
95

    
96

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

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

    
116

    
117

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

    
125

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

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

    
144

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

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

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

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

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

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

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

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

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

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

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

    
238

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

    
251

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

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

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

    
278

    
279

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

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

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

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

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

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

    
333

    
334

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

    
346

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

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

    
369

    
370

    
371

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

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

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

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

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

    
407

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

    
414

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

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

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

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

    
439

    
440

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

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

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

    
461

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

    
469
        std::map<std::string,std::string> properties; /*!< map of properties used for the transformation as (string, string) pairs */
470
    SaxonApiException * exception;
471
};
472

    
473

    
474
#endif /* SAXON_XSLT30_H */
(37-37/52)