FileWriter Component

The X:Forge FileWriter component is a component that can be used to write files as a side-effect of processing an X:Forge document. The files will have the same encoding that was set for the appropriate XForgeProcessor instance. The Test application sets the encoding of the XML file to be processed as the encoding of the XForgeProcessor. Other applications using X:Forge may choose to set a different encoding, but are then responsible for any compatibility problems between XML document encoding and the encoding they choose to set for the XForgeProcessor.

Configuration

Declaration

The component has to be declared in the configuration file in order to use it in the system. To declare the FileWriter component just configure associate an alias to the org.bibop.xml.xforge.components.file.FileWriterComponent. It's also possible to configure the exceptions handling specifying the "handle-errors-internally" attribute: its default value is true. When "handle-errors-internally" is set to false an occurring exception is thrown: changing it to true means that the exception is formatted in XML and sent to the framework as an ordinary XML data flow. 


<component role="process" class="org.apache.avalon.excalibur.component.DefaultComponentSelector">
	<component-instance name="FileWriter"
		class="org.bibop.xml.xforge.components.file.FileWriterComponent"
		handle-errors-internally="true"
		logger="mylogger">
	</component-instance>
</component>

Usage

Invocation

Once declared and configured the component can be used straight away in XML documents by invoking it like this: 


<xf:process using="FileWriter">
	<xf:parameter name="content">Some content...</xf:parameter>
	<xf:parameter name="filename">test/filewriter.txt</xf:parameter>
	<xf:parameter name="append">false</xf:parameter>
</xf:process>

The append parameter determines, if the content is appended to the end of the specified file (value true) or if the file is overwritten entirely (value false).

Resulting XML

The FileWriter components generates no XML output, instead the specified file is written with the specified content.

Errors

Error Handling

If the component is configured to handle exceptions internally, when an exception occurs, the resulting XML is the exception formatted. Here follows an example: 


<error>te1st/filewriter.txt (No such file or directory)
<stack-trace>java.io.FileNotFoundException:
  te1st/filewriter.txt (No such file or directory)  at
  java.io.FileOutputStream.openAppend(Native Method)  at
  java.io.FileOutputStream.&lt;init>
	(FileOutputStream.java:174)
  at
  java.io.FileOutputStream.&lt;init>
	(FileOutputStream.java:102)
  at
  org.bibop.xml.xforge.components.file.FileWriterComponent.toSax
	(FileWriterComponent.java:62)
  at
  org.bibop.xml.xforge.ProcessElement.toSax
	(ProcessElement.java:319)
  at
  org.bibop.xml.xforge.XForgeProcessor.endElement
	(XForgeProcessor.java:585)
  at
  org.apache.xerces.parsers.AbstractSAXParser.endElement
	(AbstractSAXParser.java:585)
  at
  org.apache.xerces.impl.XMLNamespaceBinder.handleEndElement
	(XMLNamespaceBinder.java:898)
  at
  org.apache.xerces.impl.XMLNamespaceBinder.endElement
	(XMLNamespaceBinder.java:644)
  at
  org.apache.xerces.impl.XMLDocumentFragmentScannerImpl.scanEndElement
	(XMLDocumentFragmentScannerImpl.java:1008)
  at
  org.apache.xerces.impl.XMLDocumentFragmentScannerImpl$FragmentContentDispatcher.dispatch
	(XMLDocumentFragmentScannerImpl.java:1469)
  at
  org.apache.xerces.impl.XMLDocumentFragmentScannerImpl.scanDocument
	(XMLDocumentFragmentScannerImpl.java:329)
  at
  org.apache.xerces.parsers.DTDConfiguration.parse
	(DTDConfiguration.java:525)
  at
  org.apache.xerces.parsers.DTDConfiguration.parse
	(DTDConfiguration.java:581)
  at
  org.apache.xerces.parsers.XMLParser.parse
	(XMLParser.java:152)
  at
  org.apache.xerces.parsers.AbstractSAXParser.parse
	(AbstractSAXParser.java:1175)
  at org.bibop.xml.xforge.Test.test
	(Test.java:206)
  at org.bibop.xml.xforge.Test.main
	(Test.java:122)
</stack-trace>
</error>

Otherwise, if the component is configured not to handle exceptions, the error is just re-thrown to the caller.