Configuring an XMLPrintStream Object

Figure 1. Configuring an XMLPrintStream

setPrinterName(String name);
setPaperTray(String tray);
setUserName(String user);
setEmailAddress(String email);
setEncoding(String encoding);
setJobType(String job);

Once instantiated, an XMLPrintStream object can be configured. In Default Configuration for XMLPrintStream the default configuration was covered. You can override the printer name and paper tray values using the setPrinterName and setPaperTray methods respectively. In addition, you can also set a user name and an e-mail address for the print job. The user name might be that of the user who initiated the print job, or any other user name you prefer to use. The e-mail address, similarly, can be any e-mail address you want to associate with the job.

The encoding can also be set here. This encoding is used within the XMLServer for such purposes as printing documents in the specific encoding. If the encoding is not explicitly set through the setEncoding method, then the value will be taken from the curam.xmlserver.fileencoding configuration property. If this property is not set, then the default encoding of UTF-8 will be used.

Note: It is important to set the encoding correctly when using XMLDocument and XMLPrintStream classes together. For example, if you create an XMLDocument class with an encoding of UTF-8 and you create the XMLPrintStream class setting the encoding to be US-ASCII, there may be some issues with the document being printed. As US-ASCII contains a smaller character code set than UTF-8, some characters may not be supported and therefore when printing the document, the resulting document may contain unrecognizable characters. Therefore, if you wish to have the UTF-8 document printed correctly, you should set the encoding of the XMLPrintStream instance to use UTF-8 encoding. Please see Encoding for further information on encoding.

All the parameters are strings and you must respect the requirement of XML that certain characters must be replaced with character entities. You can use the XMLDocument. escape(String value) method for this conversion.

Overriding the default values allows you, for example, to print a document to a printer nearest the current user, rather than to a default printer.

By default, the XML Server will combine your XML data with an XSL template and attempt to render the resulting document as a PDF document. The XML is transformed based on the template locale and for Right-to-Left languages. These are the supported languages, which are specified by locale code:

Table 1. Right-to-Left Supported Languages and Locale Codes
Language	Locale Code
Arabic	ar
Farsi	fa
Hebrew	he
Hebrew	iw
Yiddish	ji
Yiddish	yi
Pashto/Pushto	ps
Urdu	ur

Due to the limitations of FOP, you must have a supporting Right-to-Left implementation in the XML Server configuration (e.g., see RenderX Configuration). For this rendering step to work, the combination of the XML data and XSL template should produce a document marked up using XSL Formatting Objects. As an alternative to PDF output, you can specify RTF, HTML or plain text output using the setJobType() method. This method can be used to specify any of the supported output formats using the appropriate constant as shown in Configuring an XMLPrintStream Object. All the constants are within the XMLPrintStreamConstants class and should be prefixed with XMLPrintStreamConstants in your code unless you have implemented this class as an interface.

Table 2. XMLPrintStream Job Types
Job Type	Description
`kJobTypePDF`	This is the default job type. The XML data will be combined with the XSL template and the resulting document will be rendered as a PDF document. The template should be developed to produce a document marked up with XSL Formatting Objects. Temporary files will be given the extension ".pdf".
`kJobTypeRTF`	The XML data will be combined with the XSL template and the resulting document will be rendered as an RTF document. The template should be developed to produce a document marked up with XSL Formatting Objects. Temporary files will be given the extension ".rtf".
`kJobTypeHtml`	The XML data will be combined with the XSL template and the resulting document is assumed to be HTML. Appropriate indentation will be applied automatically. The `<xml>` declaration at the top of the file will be omitted. The template should be developed to produce a document marked up with HTML. Temporary files will be given the extension ".html".
`kJobTypeText`	The XML data will be combined with the XSL template and the resulting document is assumed to be plain text. The `<xml>` declaration at the top of the file will be omitted. Temporary files will be given the extension ".txt".

In addition to the predefined job types it is possible to define a custom job type. If a custom job type is to be used the setJobType() method should be passed a string matching the new job type, where the job type is defined in the XML Server configuration file. For more information on defining and implementing custom job types consult Custom Configuration.