Example Java classes for XML
using the Java feature of Sybase ASE


Contents


top

Technical contacts


Phil Shaw pshaw@sybase.com (510) 922-5174
Anupam Singh singha@sybase.com (510) 922-5344


top

Introduction

  1. This directory contains the example classes used in the JCS user's manual.
  2. The sections below describe how to set up the example classes, and also show some simple examples of client-side and server-side invocation of the classes, to verify that they have been successfully installed.
  3. Tutorial descriptions of the classes are in the JCS user's manual.
  4. Specifications of the classes are in the Javadoc pages.


top

Java setup in Adaptive Server

  1. You can determine the defaults and current settings for all of the Java options in Adaptive Server as follows:

  2. sp_configure "Java Services"
    

  3. To use the Java feature in Adaptive Server, you need to enable Java:

  4. sp_configure "enable java", 1
    sp_configure "number of java sockets", 10
    

  5. When using XML facilities in Adaptive Server, you may also need to increase the size of the object heap and class heap.

  6. sp_configure "process object heap", 3000
    sp_configure "shared class heap", 3000
    

  7. When you install large jar files, you will probably need to expand the size of tempdb. This is because the installjava system utility internally copies the specified jar file to a temporary table. The jar file for the Xerces XML parser (see below) is about 1.6MB, so tempdb needs to be larger than is generally the default. The following SQL command will increase the size of tempdb by 10MB.

    • alter database tempdb on default = 10


top

jConnect

  1. The following use client JDBC facilities.
  2. To use these routines you will need jConnect 5.2. See the jConnect installation instructions for the required settings of the CLASSPATH and the environment variables JAVA_HOME and JDBC_HOME.

  3. When you use the above routines, you will need to know the jConnect server-name. You can determine it with the dsedit tool.


top

Installing the XML example classes

  1. The example classes are in the following directories:
  2. To use the example classes in a client environment, include the fully-qualified paths to the following jar files on your CLASSPATH:

  3. setenv CLASSPATH $CLASSPATH":$SYBASE/ASE-12_5/sample/JavaSql/Java-SQL-examples/java-sql-examples.jar"
    setenv CLASSPATH $CLASSPATH":$SYBASE/ASE-12_5/sample/JavaSql/SQLJ-examples/sqlj-examples.jar"
    setenv CLASSPATH $CLASSPATH":$SYBASE/ASE-12_5/sample/JavaSql/XML-examples/jcs.jar"
    

  4. To use the example classes in the Adaptive Server, install the three jar files, using the installjava command:


    installjava -f "$SYBASE/ASE-12_5/sample/JavaSql/Java-SQL-examples/java-sql-examples.jar" \
                -j "java_sql_examples_jar" -t 200 -U sa -P ""
    
    installjava -f "$SYBASE/ASE-12_5/sample/JavaSql/SQLJ-examples/sqlj-examples.jar" \
                -j "sqlj_examples_jar" -t 200 -U sa -P ""
    
    installjava -f "$SYBASE/ASE-12_5/sample/JavaSql/XML-examples/jcs.jar" -j "jcs_jar" -t 200 -U sa -P ""
    


top

The XML parser

  1. The package jcs.xml and its subpackages use the Apache Xerces XML parser, Version 1.3.1.
  2. The Xerces parser is available with free license at http://xml.apache.org.
  3. A copy of the jar distribution of the Xerces parser, and the associated license agreement, is also provided with ASE 12.5 in $SYBASE/ASE-12_5/lib/xerces.jar.
  4. This is the same parser that the ASE 12.5 XQL feature uses. You only need to install the parser once for any database in which you will use either the XQL feature or the jcs.xml example classes.
  5. To use the XML example classes (or the ASE 12.5 XQL feature), setup the jar file for the Xerces XML parser as follows:
  6. These actions can be performed with commands such as the following, referencing the copy of the Xerces jar file distributed with ASE 12.5:


      installjava -f "$SYBASE/ASE-12_5/lib/xerces.jar" -j "xerces_jar" -t 500 -U sa -P "" setenv CLASSPATH $CLASSPATH":$SYBASE/ASE-12_5/lib/xerces.jar"


top

JavaDoc

The Javadoc pages contain the specifications for the classes. Javadoc for the jcs package is in the doc directory.

The examples in the following sections are rudimentary tests to verify that the classes have been setup successfully. The examples don't describe the methods that are being called or their parameters. See the Javadoc pages or the JCS user's manual for that information.


top

Using the example XML classes in a client

  1. The example classes can be used in Java classes executed in client environments in the ways shown in the JCS user's manual.
  2. One of the example classes, jcs.xml.resultset.ResultSetXml, has methods that translate an SQL query to an XML result set, and that translate such an XML result set to an SQL script with a create statement and a list of insert statements to create and populate an SQL table with the data of the original result set.

    The main methods of the DoSql2Xml and DoXml2Sql classes provide client-side command-line invocation of those SQL-XML and XML-SQL capabilities.

    The detailed specifications for those classes and their parameters are specified in the Javadoc pages. The following is a simple introductory example.

  3. The DoSql2Xml and DoXml2Sql calls shown below use the jConnect server-name, described in jConnect.
  4. Example invocations of DoSql2Xml and DoXml2Sql are as follows:
    java jcs.xml.resultset.DoSql2Xml -S jConnect-server-name  -O client-output.xml \
         -N yes -C none \
         -Q "select 1 as 'a', 2 as 'b', 3  "
    
    java jcs.xml.resultset.DoXml2Sql -I client-output.xml \
          -O client-output.script -X "column_" -T clientcopy
    
    isql -i client-output.script -Usa -P ""
    
    

  5. The first command line invokes DoSql2Xml. That method executes the trivial query "select 1 as 'a', 2 as 'b', 3", and generates an XML document containing a representation of the SQL result set from that query. The command stores that XML document into file "client-output.xml".
  6. The second command line invokes DoXml2Sql to process the XML document contained in the file client-output.xml, which was generated by the first command line. That file contains an XML representation of the result set from the trivial example SQL query. The command generates an SQL script containing a create statement for a table named clientcopy whose columns match those of the result set, together with a series of insert statements to insert rows corresponding to those of the result set (in this example there is one row). The command stores that SQL script into the designated file, client-output.script.
  7. The last command line executes the SQL script contained in client-output.script. This yields a table named clientcopy with the same data as the result set of the original query.
  8. The XML result set and SQL script generated by the above actions are shown in The generated XML document and SQL script.
  9. For further details of the DoSql2Xml and DoXml2Sql classes and their parameters, see the Javadoc pages.


top

Using the example XML classes in the Adaptive Server

  1. The following isql script uses the classes of the jcs.xml.resultset package in the Adaptive Server.

    This script performs the same actions as in the preceeding section:

    The script is as follows (see file test-install/server-script.sql):


      -- Create a table for results create table servertest (id char(20), xml jcs.xml.resultset.ResultSetXml, script java.lang.String null) go -- Generate an XML ResultSet document with a trivial result set declare @rsx jcs.xml.resultset.ResultSetXml select @rsx = new jcs.xml.resultset.ResultSetXml ("select 1 as 'a', 2 as 'b', 3 ", "none", "yes", "") insert into servertest values("1", @rsx, null) go -- Generate an SQL script to re-create the result set, update servertest set script = xml>>toSqlScript("servercopy", "column_", "no") where id = "1" go declare @script java.lang.String select @script = script from servertest where id="1" declare @i integer select @i = jcs.util.ExecSql.statement(@script, "") go -- Display the copy table select * from servercopy go

  2. When you execute this script in isql, the last select should display the copy of the result set:
     a           b           column_3    
     ----------- ----------- ----------- 
               1           2           3 
    
    (1 row affected)
    
    

  3. You can retrieve the XML result set and the generated SQL script that were produced by the above isql script with the following client-side command-line calls:
      java jcs.util.FileUtil -S "$SERVER" -A getstring -O test-output.xml \ -Q "select xml from servertest where id='1' " java jcs.util.FileUtil -S "$SERVER" -A getstring -O test-output.script \ -Q "select script from servertest where id='1' "

    The results will be in files test-output.xml and test-output.script.

  4. The XML result set and SQL script generated by the above actions are shown in The generated XML document and SQL script.
  5. For further details of the classes referenced above and their parameters, see the Javadoc pages.


top

The generated XML document and SQL script

  1. The above sections Using the example classes in a client and Using the example classes in a server perform similar actions:
  2. Execution of the above actions in a client and in the Adaptive Server produces the same generated XML result set document and generated SQL script.
  3. The generated XML result set document is as follows:
      <?xml version="1.0"?> <!DOCTYPE ResultSet SYSTEM 'ResultSet.dtd'> <ResultSet> <ResultSetMetaData getColumnCount="3"> <ColumnMetaData getColumnDisplaySize="11" getColumnLabel="a" getColumnName="a" getColumnType="4" getPrecision="0" getScale="0" isAutoIncrement="false" isCurrency="false" isDefinitelyWritable="false" isNullable="false" isSigned="true" /> <ColumnMetaData getColumnDisplaySize="11" getColumnLabel="b" getColumnName="b" getColumnType="4" getPrecision="0" getScale="0" isAutoIncrement="false" isCurrency="false" isDefinitelyWritable="false" isNullable="false" isSigned="true" /> <ColumnMetaData getColumnDisplaySize="11" getColumnLabel="" getColumnName="" getColumnType="4" getPrecision="0" getScale="0" isAutoIncrement="false" isCurrency="false" isDefinitelyWritable="false" isNullable="false" isSigned="true" /> </ResultSetMetaData> <ResultSetData> <Row> <Column name="a">1</Column> <Column name="b">2</Column> <Column name="">3</Column> </Row> </ResultSetData> </ResultSet>

  4. The generated SQL script is as follows:
      set quoted_identifier on create table test_123 ( a integer not null , b integer not null , column_3 integer not null ) go insert into test_123 values ( 1, 2, 3 ) go

    Note: When the SQL script is generated, a parameter indicates whether you want to include the "go" commands. These are required when the script is executed by ISQL, and not allowed when the script is executed with a JDBC call. Therefore, the above client-side example includes the "go" commands and the server-side example omits them. See the Javadoc pages and the JCS user's manual for further discussion of this option.

  5. To remove the effect of these install tests:
      drop table servercopy drop table clientcopy drop table serverout


top

Changes from the ASE 12.0 example classes

The changes made in the example classes from ASE 12.0 are as follows:

The JDBCExamples class

The jcs.util.StringUtil class

The jcs.xml package


top