• Chapter 1: Getting Started with Stylus Studio
• Chapter 2: Editing and Querying XML
• Chapter 3: Converting Non-XML Files to XML
  • Overview
  • Choosing an Input File
  • The Convert to XML Editor
  • Parts of an Input File
  • Working with Regions
  • Working with Fields
  • Controlling XML Output
  • Creating a Convert to XML Converter
  • Using Converters in Stylus Studio
  • Invoking an Adapter Programmatically
    • Adapter URLs
    • The StylusFile Object
    • Constructing Your Own Adapter URL
    • Example - demo.bat
    • More About the Stylus Studio File System Java API
  • Properties Reference
• Chapter 4: Working with XSLT
• Chapter 5: Creating XSLT Using the XSLT Mapper
• Chapter 6: Debugging Stylesheets
• Chapter 7: Defining XML Schemas
• Chapter 8: Defining Document Type Definitions
• Chapter 9: Writing XPath Expressions
• Chapter 10: Working with XQuery in Stylus Studio
• Chapter 11: Composing Web Service Calls
• Chapter 12: Accessing Relational Data as XML
• Chapter 13: Extending Stylus Studio
• Chapter 14: Stylus Studio GUI Reference

Home > Online Product Documentation > Table of Contents > Invoking an Adapter Programmatically

Invoking an Adapter Programmatically

You can use the Stylus Studio File System Java API to invoke an adapter programmatically. This section provides background information on using adapter URLs in Stylus Studio and in your applications, and it describes demo.bat, a simple Java program installed with Stylus Studio.

This section covers the following topics:

Adapter URLs

Stylus Studio uses URLs extensively to reach a variety of data sources. For example, if you use the built-in CSV converter to open the three.txt file in the \examples\Adapters directory as an XML document, Stylus Studio builds the following URL:

adapter:CSV:newline=crlf:sep=,:first=no:escape=\:quotes="
              '?file:///c:/Program 
Files/Stylus Studio XML Professional Edition/examples/Adapters/three.txt
               

            

The instructions to the adapter engine from this instance of the adapter URL are described in Table 20.

While the basic format of the adapter URL is the same from one adapter to another, there are differences. For example:

adapter:///myConverter.conv?file:inventory.txt
               

            

This converter uses myConverter.conv to convert the file inventory.txt to some format (specified in the converter file when you built it).

Where Adapter URLs are Displayed in Stylus Studio

Adapter URLs are displayed

Figure 186. Adapter URL Displayed in Project WIndow

Figure 187. Adapter URL Displayed in the Select XML Converter Dialog Box

You can use either as sources for the adapter URL strings you use in your Java applications. See Constructing Your Own Adapter URL for more information.

The StylusFile Object

In Java, we write the following to retrieve the content of a file, myfile.txt, that resides on an FTP server:

java.net.URL myUrl = new java.net.URL("ftp://myserver/myfile.txt");
               
java.io.InputStream inputstream = myUrl.openStream();
               

            

The content of myfile.txt is placed in an instance of java.net.URL called myUrl.

The StylusFile object in the Stylus Studio File System Java API is similar to java.net.URL. In Stylus Studio, you use the createStylusFile() method in the StylusFileFactory class to create an instance of a StylusFile object, the contents of which is specified by an adapter URL. Consider the following simple Java application, which uses the URL composed by Stylus Studio that was introduced in Adapter URLs.

StylusFile myStylusFile = 
StylusFileFactory.getFactory().createStylusFile("adapter:CSV:newline=crlf:
sep=,:first=yes:escape=/:quotes='\"?file:///c:/Program Files/Stylus Studio XML 
Professional Edition/examples/Adapters/three.txt");
               
 
               
java.io.InputStream inputstream = myStylusFile.getInputStream();
               

            

In this example, the InputStream object holds the conversion result supplied by the adapter URL (that is, the conversion of three.txt using the CSV adapter).

See Example - demo.bat for a description of the sample Java application installed with Stylus Studio, which illustrates different uses of the adapter URL.

Constructing Your Own Adapter URL

Generally speaking, you should use Stylus Studio to construct adapter URLs, which you can then copy, as strings, into a Java application. Adapter URLs can be complex - properties and their values vary from one adapter to another, for example - so using Stylus Studio to construct them helps reduce errors in your applications.

Using the URL in the Select XML Converter Dialog Box

To construct an adapter URL using the URL in the Select XML Converter dialog box:

Using the URL in the Properties Window

To construct an adapter URL using the URL in the Properties window:

The complete URL appears in the text editor.

Figure 188. Copying a URL to a Text Editor

Example - demo.bat

The following example shows an implementation of a simple application built using the Stylus Studio File System Java API. The application, demo.bat, shows three uses of the invoking adapter URLs to convert files using built-in and user-defined converters.

Demonstration Files

The files required to run this demonstration are installed in the \examples\Adapters directory where you installed Stylus Studio. They are summarized in Table 21.

demo.java

Here is the demo.java file called by demo.bat.

import java.io.File;
               
import java.io.FileOutputStream;
               
import java.io.OutputStream;
               
import java.io.FileInputStream;
               
import java.io.InputStream;
               
import java.io.IOException;
               
 
               
import com.exln.stylus.io.StylusFile;
               
import com.exln.stylus.io.StylusFileFactory;
               
 
               
public class demo {
               
	public static void main(String args[]) {
               
		StylusFileFactory sff = StylusFileFactory.getFactory();
               
 
               
		try {
               
			StylusFile in_1 = 
sff.createStylusFile("adapter:///CSV:sep=,:first=yes?file:one.csv");
               
			File out_1 = new File("one.xml");
               
			InputStream is = in_1.getInputStream();
               
			OutputStream os = new FileOutputStream(out_1);
               
			copy(is, os);
               
			in_1.close();
               
			System.out.println("test 1 succeeded: one.csv -> one.xml");
               
		} catch (IOException ioe) {
               
			ioe.printStackTrace();
               
		}
               
 
               
		try {
               
			File in_2 = new File("two.xml");
               
			StylusFile out_2 = 
sff.createStylusFile("adapter:///CSV:sep=,:first=yes?file:two.csv");
               
			InputStream is = new FileInputStream(in_2);
               
			OutputStream os = out_2.getOutputStream();
               
			copy(is, os);
               
			out_2.close();
               
			System.out.println("test 2 succeeded: two.xml -> two.csv");
               
		} catch (IOException ioe) {
               
			ioe.printStackTrace();
               
		}
               
 
               
 
               
		try {
               
			StylusFile in_3 = 
sff.createStylusFile("adapter:///three.conv?file:three.txt");
               
			File out_3 = new File("three.xml");
               
			InputStream is = in_3.getInputStream();
               
			OutputStream os = new FileOutputStream(out_3);
               
			copy(is, os);
               
			in_3.close();
               
			System.out.println("test 3 succeeded: three.txt -> three.xml");
               
		} catch (IOException ioe) {
               
			ioe.printStackTrace();
               
		}
               

            

	static void copy(InputStream is, OutputStream os) throws IOException {
               
		byte buffer[] = new byte[8192];
               
		int bytesRead;
               
		while ((bytesRead = is.read(buffer)) != -1) {
               
			os.write(buffer, 0, bytesRead);
               
		}
               
		os.flush();
               
		os.close();
               
	}
               
 
               
}
               

            

Required classes

The file starts with the Java and Stylus Studio File System Java API classes and interfaces required by demo.java. The StylusFile interface is used to define an abstract representation of a file in a custom file system; the StylusFileFactory class enables the demo.bat application to read and write files.

import java.io.File;
               
import java.io.FileOutputStream;
               
import java.io.OutputStream;
               
import java.io.FileInputStream;
               
import java.io.InputStream;
               
import java.io.IOException;
               
 
               
import com.exln.stylus.io.StylusFile;
               
import com.exln.stylus.io.StylusFileFactory;
               

            

Setting the installation directory

User-defined converters ( .conv files) are saved to the XML Converters file system. If your application uses user-defined converters, such as the three.conv file used by the demo.bat, you need to identify the Stylus Studio installation directory so set the converter can be located. You can do this using System.setProperty, as shown in the following lines of code.

public class demo {
               
	public static void main(String args[]) {
               
	//	System.setProperty("com.stylusstudio.rootdir", "C:\\Program 
Files\\Stylus Studio XML Professional Edition");
               

            

These lines are commented out in demo.java because you can also specify the Stylus Studio installation directory using the -D argument at the command line, as shown in demo.bat: "-Dcom.stylusstudio.rootdir=%STYLUS%").

Creating an instance of StylusFile

Next, the StylusFileFactory class is called to create a new instance of the StylusFile, object, named sff in this demonstration.

		StylusFileFactory sff = StylusFileFactory.getFactory();
               

            

The copy () method

The copy() method is used to create new files by saving the file specified in the InputStream ( is) to the file specified in the OutputStream ( os).

The copy() method is defined in demo.java as follows:

	static void copy(InputStream is, OutputStream os) throws IOException {
               
		byte buffer[] = new byte[8192];
               
		int bytesRead;
               
		while ((bytesRead = is.read(buffer)) != -1) {
               
			os.write(buffer, 0, bytesRead);
               
		}
               
		os.flush();
               
		os.close();
               
	}
               

            

Whether your files are saved as XML or non-XML depends on how the InputStream and the OutputStream in your applications are defined. You can define either stream using an adapter URL. When the

Converting a file to XML

Once the new instance of StylusFile has been created, the demo.bat application can execute its first exception block. The adapter URL specified in this exception block uses the built-in Comma-Separated Values converter ( adapter:///CSV:) to convert a CSV file named one.csv into an XML document named one.xml.

		try {
               
			StylusFile in_1 = 
sff.createStylusFile("adapter:///CSV:sep=,:first=yes?file:one.csv");
               
			File out_1 = new File("one.xml");
               
			InputStream is = in_1.getInputStream();
               
			OutputStream os = new FileOutputStream(out_1);
               
			copy(is, os);
               
			in_1.close();
               
			System.out.println("test 1 succeeded: one.csv -> one.xml");
               
		} catch (IOException ioe) {
               
			ioe.printStackTrace();
               
		}
               

            

In this block of code, the adapter URL is used to specify the InputStream.

Converting an XML document to another format

This exception block specifies the OutputStream using the adapter URL to convert an XML document named two.xml to a CSV file named two.txt.

		try {
               
			File in_2 = new File("two.xml");
               
			StylusFile out_2 = 
sff.createStylusFile("adapter:///CSV:sep=,:first=yes?file:two.csv");
               
			InputStream is = new FileInputStream(in_2);
               
			OutputStream os = out_2.getOutputStream();
               
			copy(is, os);
               
			out_2.close();
               
			System.out.println("test 2 succeeded: two.xml -> two.csv");
               
		} catch (IOException ioe) {
               
			ioe.printStackTrace();
               
		}
               

            

Using an adapter URL with a user-defined converter

The final exception block uses a user-defined converter built using the Convert to XML module ( three.conv) to convert a fixed-width file name three.txt to and XML document named three.xml.

		try {
               
			StylusFile in_3 = 
sff.createStylusFile("adapter:///three.conv?file:three.txt");
               
			File out_3 = new File("three.xml");
               
			InputStream is = in_3.getInputStream();
               
			OutputStream os = new FileOutputStream(out_3);
               
			copy(is, os);
               
			in_3.close();
               
			System.out.println("test 3 succeeded: three.txt -> three.xml");
               
		} catch (IOException ioe) {
               
			ioe.printStackTrace();
               
		}
               

            

As with the first exception block, this block uses the adapter URL to specify the InputStream.

More About the Stylus Studio File System Java API

You can learn about other uses for the Stylus Studio File System Java API in Stylus Studio File System Java API, located in Chapter 13Extending Stylus Studio.

Javadoc

Javadoc for the Stylus Studio File System Java API is installed with Stylus Studio. It is available in the Stylus Studio /doc/Javadoc directory. Open index.html to get started. The Javadoc is also available on the Stylus Studio Web site, www.stylusstudio.com.