White Papers/API and Connectors/DiType Java references

From Docs

Jump to: navigation, search

Get PDF

< API and Connectors

Contents

DiType Java references

Overview

  • Java Packages name are com.renderx.ditypex (high-level programming interface) and com.renderx.ditypex.cliser (low-level programming interface).
  • A Formatter object provides an opportunity to format XML/XSL FO documents. In case of XML, assosiated stylesheets is always passed as processing instruction. For some XML documents - such as DocBook, WordML, DITA and etc. - stylesheet is predefined in DiType transformer configuration. For each document one Formatter instanes is created. During each session only one document (with its separate logger and properties) can be formatted.
public class Formatter{            
  public Formatter();                                        
  public Formatter(Logger logger);
  public Formatter(java.util.Properties options);
  public Formatter(Logger logger, java.util.Properties options);
  public FormattedInputStream render(javax.xml.transform.sax.SAXSource source, 
    String infmt, mode);
  public FormattedInputStream render(javax.xml.transform.sax.DOMSource source, 
    String infmt, String mode);
  public FormattedInputStream render(javax.xml.transform.stream.StreamSource source, 
    String infmt, String mode);
  public FormattedInputStream render(java.io.InputStream source, String systemId, 
    String infmt, String mode);
  public void setDitypeParameters(java.util.Properties params);
  public static java.lang.String urlEncode(java.lang.String systemId);
}
  • Interface Logger is used to log messages during formatting process. User can implement his own logger to pass to Formatter.
public interface Logger{
  public void error(string message); 
  public void info(string message); 
  public void log(string message); 
  public void warning(string message); 
}  
  • Class DefaultLogger implements a Logger interface and is used as default logger in Formatter.
public class DefaultLogger implements Logger{
  public DefaultLogger();
  public DefaultLogger(java.io.Writer writer);
  public void error(string message); 
  public void info(string message); 
  public void log(string message); 
  public void warning(string message); 
}  
  • A FormattedInputStream object obtains a formatted input stream of document from socket (java.io.InputStream). It provides an opportunity to modify stream (for example, stream was formatted in XEP format) and again pass it to Formatter for rendering. A FormattedInputStream object is returned by render method of Formatter class.
  • Default input format of the document is "auto". Possible values of input format are predefined in the transformer configuration file (transform.conf).
  • A Client, ErrorHandler, Protocol and ProtocolException objects are used on lower level of connectors to pass Ditype for rendering input documents and to get an output.

Signature of methods and constructors

public Formatter();                                        

Description: Creates a Formatter object with DefaultLogger and default options.

public Formatter(Logger logger);

Description: Creates a Formatter object with specified logger and default options. Parameters:

  • Logger logger - user specified logger
public Formatter(java.util.Properties options);

Description: Creates a Formatter object with DefaultLogger and specified options. Parameters:

  • java.util.Properties options - user specified options;
public Formatter(Logger logger, java.util.Properties options);

Description: Creates a Formatter object with specified logger and options. Parameters:

  • Logger logger - user specified logger;
  • java.util.Properties options - user specified options;
public FormattedInputStream render(javax.xml.transform.sax.SAXSource source, 
    String infmt, mode);
  public FormattedInputStream render(javax.xml.transform.sax.DOMSource source, 
    String infmt, String mode);
  public FormattedInputStream render(javax.xml.transform.stream.StreamSource source, 
    String infmt, String mode);
  public FormattedInputStream render(java.io.InputStream source, String systemId, 
    String infmt, String mode);

Description: Formats document in specified mode and returns input stream as a result. Parameters:

  • source - input document
  • systemId - system ID of input document
  • infmt - input document format
  • mode - output format

Return value: FormattedInputStream

public void setDitypeParameters(java.util.Properties params);

Description: Sets DiType parameters. Parameters:

  • params - DiType parameters (e.g. DITYPE_DATA_PORT and DITYPE_HOST)
public static java.lang.String urlEncode(java.lang.String systemId)

Description: URL encoding function. Unlike java.net.URLEncoder.encode(), it encodes spaces as '%20', not '+'. Characters outside US_ASCII are encoded in UTF-8. Parameters:

  • params - a system ID

Return value: encoded URL string

Passing DiType configuration parameters to connector

A Formatter object connects to DiType server at localhost:19790. You may need to change this value if your DiType server is launched on another computer or is using another port. It is possible to pass the following parameters:

  • DITYPE_HOST - DiType server host;
  • DITYPE_DATA_PORT - DiType data port;
  • DEBUG - debug mode

The parameters can be set as system property (the Java system property can be passed into the application by using -D flag, e.g. java -DDITYPE_HOST=host YourClass) or directly passed with setDitypeParameters method to Formatter.

Compilation

Before compiling Java connectors with all plug-ins, the following components must be installed:

  • Sun JDK 1.4 or higher;
  • Ant 1.5 or higher;
  • jEdit;
  • Servlet container compatible with Servlet 2.2 API;
  • <oXygen/> XML Editor 8.0 or higher;
  • Cocoon 2.1.x
  • Java 2 Enterprise Edition

Define the following Ant properties:

  • ditypex.dir - folder to put compiled classes and DiType JAR;
  • jedit.dir - jEdit home directory;
  • servlet.interface - path to the jar file providing the servlet interface;
  • junit.jar - path to junit.jar
  • oxygen.dir - path to oXygen home directory
  • cocoon.interface - path to the jar files providing the cocoon interface;
  • j2ee.jar - path to j2ee.jar

Ant script includes the following basic targets:

  • make.jar - compile basic DiType JAR without plug-ins;
  • assembly - default target; compile and build DiType JAR and all connectors.

If you need only DiType JAR, you need only JDK and Appache Ant installation. In that case you need to define only ditypex.dir Ant property.

To build separate example do the following:

  • run ant make.jar in Java connector home directory;
  • go to desired connector folder. Define Ant properties in build.props file and run Ant. Built archives will be available in current build directory.

Example

public class SAXInput {
  /**
  * Main function. Produce a PostScript from input document 
  * represented as SAX source.
  * @param args input and output file names
  */
  public static void main(String[] args){
    int CHUNKSIZE = 512;

    if (args.length != 2) {
      System.out.println("Usage: java SAXInput <input> <output>");
       System.exit(1);
    }

    // Create an instance of Ditype formatter
    com.renderx.ditypex.Formatter formatter = new com.renderx.ditypex.Formatter(
            new com.renderx.ditypex.DefaultLogger());

    // Create a JAXP SAXSource for the source
    javax.xml.transform.sax.SAXSource source = null;
    try {
      java.io.File in = new java.io.File(args[0]);
      org.xml.sax.InputSource saxsrc = new org.xml.sax.InputSource(in.toURL().toString());
      source = new javax.xml.transform.sax.SAXSource(saxsrc);
    } catch (Exception e) {
      System.out.println("Source creation failed: " + e.toString());
      System.exit(1);
    }

    // Open the output file
    java.io.OutputStream out = null;
	
    // Open the input stream
    java.io.InputStream stream = null;
    try {
      out = new java.io.FileOutputStream(args[1]);
    } catch (Exception e) {
      System.out.println("Could not open output file: " + e.toString());
      System.exit(1);
    }
	
    // Render the document directly to the PostScript file
    try {
      try {
        // Format source and return formatted input stream
        stream = formatter.render(source, "auto", "ps");
			
        byte buffer[] = new byte[CHUNKSIZE];
        int bytesRead;
        while ((bytesRead = stream.read(buffer)) != -1) {
          out.write(buffer, 0, bytesRead);
        }
      } finally {
        out.close();
        stream.close();
      }
    } catch (Exception e) {
      System.out.println("Rendering failed: " + e.toString());
      System.exit(1);
    }
  }
}

Links

DiType API for Java is available here.


Angelina Andriasyan

Personal tools