Home

	Expand Search

Java in Adaptive Server Enterprise

Chapter 12 Reference Topics

Chapter 12

Reference Topics

This chapter presents information on several reference topics.

Assignments

This section defines the rules for assignment between SQL data items whose datatypes are Java-SQL classes.

Each assignment transfers a source instance to a target data item:

• For an insert statement specifying a table that has a Java-SQL column, refer to the Java-SQL column as the target data item and the insert value as the source instance.

• For an update statement that updates a Java-SQL column, refer to the Java-SQL column as the target data item and the update value as the source instance.

• For a select or fetch statement that assigns to a variable or parameter, refer to the variable or parameter as the target data item and the retrieved value as the source instance.

If the source is a variable or parameter, then it is a reference to an object in the Java VM. If the source is a column reference, which contains a serialization, then the rules for column references (see Java-SQL column references) yield a reference to an object in the Java VM. Thus, the source is a reference to an object in the Java VM.

Assignment rules at compile-time

1. Define SC and TC as compile-time class names of the source and target. Define SC_T and TC_T as classes named SC and DT in the database associated with the target. Similarly, define SC_S and TC_S as classes named SC and DT in the database associated with the source.

2. SC_T must be the same as TC_T or a subclass of TC_T.

Assignment rules at runtime

Assume that DT_SC is the same as DT_TC or its subclass.

• Define RSC as the runtime class name of the source value. Define RSC_S as the class named RSC in the database associated with the source. Define RSC_T as the name of a class RSC_T installed in the database associated with the target. If there is no class RSC_T, then an exception is raised. If RSC_T is neither the same as TC_T nor a subclass of TC_T, then an exception is raised.

• If the databases associated with the source and target are not the same database, then the source object is serialized by its current class, RSC_S, and that serialization is deserialized by the class RSC_T that it will be associated with in the database associated with the target.

• If the target is a SQL variable or parameter, then the source is copied by reference to the target.

• If the target is a Java-SQL column, then the source is serialized, and that serialization is deep copied to the target.

Allowed conversions

You can use convert to change the expression datatype in these ways:

• Convert Java types where the Java datatype is a Java object type to the SQL datatype shown in "Datatype mapping between Java and SQL". The action of the convert function is the mapping implied by the Java-SQL mapping.

• Convert SQL datatypes to Java types shown in "Datatype mapping between Java and SQL". The action of the convert function is the mapping implied by the SQL-Java mapping.

• Convert any Java-SQL class installed in the SQL system to any other Java-SQL class installed in the SQL system if the compile-time datatype of the expression (source class) is a subclass or superclass of the target class. Otherwise, an exception is raised.

The result of the conversion is associated with the current database.

See "Using the SQL convert function for Java subtypes," for a discussion of the use of the convert function for Java subtypes.

Transferring Java-SQL objects to clients

When a value whose datatype is a Java-SQL object type is transferred from Adaptive Server to a client, the data conversion of the object depends on the client type:

• If the client is an isql client, the toString( ) or similar method of the object is invoked and the result is truncated to varchar, which is transferred to the client.

  The number of bytes transferred to the client is dependent on the value of the @@stringsize global variable. The default value is 50 bytes. See "Representing Java instances" for more information.

• If the client is a Java client that uses jConnect 4.0 or later, the server transmits the object serialization to the client. This serialization is seamlessly deserialized by jConnect to yield a copy of the object.

• If the client is a bcp client:

  • If the object is a column declared as in row, the serialized value contained in the column is transferred to the client as a varbinary value of length determined by the size of the column.

  • Otherwise, the serialized value of the object (the result of the writeObject method of the object) is transferred to the client as an image value.

Supported Java API packages, classes, and methods

Adaptive Server supports many but not all classes and methods in the Java API. In addition, Adaptive Server may impose security restrictions and implementation limitations. For example, Adaptive Server does not support all of the thread creation and manipulation facilities of java.lang.Thread.

The supported packages are installed with Adaptive Server and are always available. They cannot be installed by the user.This section lists:

• Supported Java packages and classes

• Unsupported Java packages

• Unsupported java.sql methods

Supported Java packages and classes

• java.io

  • Externalizable

  • DataInput

  • DataOutput

  • ObjectInputStream

  • ObjectOutputStream

  • Serializable

• java.lang - see "Unsupported java.sql methods and interfaces" for a list of the unsupported classes in java.lang.

• java.math

• java.net - see Chapter 11, "Network Access Using java.net"

• java.sql - see "Unsupported java.sql methods and interfaces" for a list of the unsupported methods and interfaces in java.sql.

• java.text

• java.util

• java.util.zip

Unsupported Java packages and classes

• java.applet

• java.awt

• java.awt.datatransfer

• java.awt.event

• java.awt.image

• java.awt.peer

• java.beans

• java.lang.Thread

• java.lang.ThreadGroup

• java.rmi

• java.rmi.dgc

• java.rmi.registry

• java.rmi.server

• java.security

• java.security.acl

• java.security.interfaces

Unsupported java.sql methods and interfaces

• Connection.commit( )

• Connection.getMetaData( )

• Connection.nativeSQL( )

• Connection.rollback( )

• Connection.setAutoCommit( )

• Connection.setCatalog( )

• Connection.setReadOnly( )

• Connection.setTransactionIsolation( )

• DatabaseMetaData.* - DatabaseMetaData is supported except for these methods:

  • deletesAreDetected()

  • getUDTs()

  • insertsAreDetected()

  • updatesAreDetected()

  • othersDeletesAreVisible()

  • othersInsertsAreVisible()

  • othersUpdatesAreVisible()

  • ownDeletesAreVisible()

  • ownInsertsAreVisible()

  • ownUpdatesAreVisible()

• PreparedStatement.setAsciiStream( )

• PreparedStatement.setUnicodeStream( )

• PreparedStatement.setBinaryStream( )

• ResultSetMetaData.getCatalogName( )

• ResultSetMetaData.getSchemaName( )

• ResultSetMetaData.getTableName( )

• ResultSetMetaData.isCaseSensitive( )

• ResultSetMetaData.isReadOnly( )

• ResultSetMetaData.isSearchable( )

• ResultSetMetaData.isWritable( )

• Statement.getMaxFieldSize( )

• Statement.setMaxFieldSize( )

• Statement.setCursorName( )

• Statement.setEscapeProcessing( )

• Statement.getQueryTimeout( )

• Statement.setQueryTimeoutt()

Invoking SQL from Java

Adaptive Server supplies a native JDBC driver, java.sql, that implements JDBC 1.1 specifications. It is described at http://www.javasoft.com. java.sql enables Java methods executing in Adaptive Server to perform SQL operations.

Special considerations

java.sql.DriverManager.getConnection( ) accepts these URLs:

• null

• "" (the null string)

• jdbc:default:connection

When invoking SQL from Java some restrictions apply:

• A SQL query that is performing update actions (update, insert, or delete) cannot use the facilities of java.sql to invoke other SQL operations that also perform update actions.

• Triggers that are fired by SQL using the facilities of java.sql cannot generate result sets.

• java.sql cannot be used to execute extended stored procedures or remote stored procedures.

Transact-SQL commands from Java methods

You can use certain Transact-SQL commands in Java methods called within the SQL system. Table 12-1 lists Transact-SQL commands and whether or not you can use them in Java methods. You can find further information on most of these commands in the Sybase Adaptive Server Enterprise Reference Manual.

Table 12-2 lists set command options and whether or not you can use them in Java methods.

Datatype mapping between Java and SQL

Adaptive Server maps SQL datatypes to Java types (SQL-Java datatype mapping) and Java scalar types to SQL datatypes (Java-SQL datatype mapping). Table 12-3 shows SQL-Java datatype mapping.

Table 12-4 shows Java-SQL datatype mapping.

Java-SQL identifiers

Description

Java-SQL identifiers are a subset of Java identifiers that can be referenced in SQL.

Syntax

java_sql_identifier ::= alphabetic character |     underscore (_) symbol
    [alphabetic character | arabic numeral |     underscore(_) symbol | 
    dollar ($) symbol ]

Usage

• Java-SQL identifiers can be a maximum of 255 bytes in length if they are surrounded by quotation marks. Otherwise, they must be 30 bytes or fewer.

• The first character of the identifier must be either an alphabetic character (uppercase or lowercase) or the underscore (_) symbol. Subsequent characters can include alphabetic characters (uppercase or lowercase), numbers, the dollar ($) symbol, or the underscore (_) symbol.

• Java-SQL identifiers are always case sensitive.

• Delimited identifiers are object names enclosed in double quotes. Using delimited identifiers for Java-SQL identifiers allows you to avoid certain restrictions on the names of Java-SQL identifiers.

  You can use double quotes with Java-SQL identifiers whether the set quoted_identifier option is on or off.

• Delimited identifiers allow you to use SQL reserved words for packages, classes, methods, and so on. Each time you use the delimited identifier in a statement, you must enclose it in double quotes. For example:

  create table t1
              (c1 char(12)
              c2 p1."select".p2."jar")

• Double quotes surround only individual Java-SQL identifiers, not the fully qualified name.

See also

For additional information about identifiers, see Chapter 5, "Transact-SQL Topics," in the Reference Manual.

Java-SQL class and package names

Description

To reference a Java-SQL class or package, use the following syntax:

Syntax

java_sql_class_name ::=  [java_sql_package_name.]java_sql_identifier

java_sql_package_name ::=
    [java_sql_package_name.]java_sql_identifier

Parameters

The fully qualified name of a Java-SQL class in the current database.

The fully qualified name of a Java-SQL package in the current database.

See Java-SQL identifiers.

Usage

For Java-SQL class names:

• A class name reference always refers to a class in the current database.

• If you specify a Java-SQL class name without referencing the package name, only one Java-SQL class of that name must exist in the current database, and its package must be the default (anonymous) package.

• If a SQL user-defined datatype and a Java-SQL class possess the same sequence of identifiers, Adaptive Server uses the SQL user-defined datatype name and ignores the Java-SQL class name

For Java-SQL package names:

• If you specify a Java-SQL subpackage name, you must reference the subpackage name with its package name:

  java_sql_package_name.java_sql_subpackage_name

• Use Java-SQL package names only as qualifiers for class names or subpackage names and to delete packages from the database using the remove java command.

Java-SQL column declarations

Description

To declare a Java-SQL column when you create or alter a table, use the following syntax:

Syntax

java_sql_column ::= column_name  java_sql_class_name

Parameters

Specifies the syntax of Java-SQL column declarations.

The name of the Java-SQL column.

The name of a Java-SQL class in the current database. This is the "declared class" of the column.

Usage

• The declared class must implement either the Serializable or Externalizable interface.

• A Java-SQL column is always associated with the current database.

• A Java-SQL column cannot be specified as:

  • not null

  • unique

  • A primary key

See also

You use a Java-SQL column declaration only when you create or alter a table. See the create table and alter table information in the Reference Manual.

Java-SQL variable declarations

Description

Use Java-SQL variable declarations to declare variables and stored procedure parameters for datatypes that are Java-SQL classes.

Syntax

java_sql_variable  ::=  @variable_name java_sql_class_name

java_sql_parameter  ::=  @parameter_name java_sql_class_name

Parameters

Specifies the syntax of a Java-SQL variable in a SQL stored procedure.

Specifies the syntax of a Java-SQL parameter in a SQL stored procedure.

The name of a Java-SQL class in the current database.

Usage

A java_sql_variable or java_sql_parameter is always associated with the database containing the stored procedure.

See also

Refer to the Reference Manual for more information about variable declarations.

Java-SQL column references

Description

To reference a Java-SQL column, use the following syntax:

Syntax

column_reference ::=
    [ [ [database_name.]owner.]table_name.]column_name
    |  database_name..table_name.column_name

Parameters

A reference to a column whose datatype is a Java-SQL class.

Usage

• If the value of the column is null, then the column reference is also null.

• If the value of the column is a Java serialization, S, and the name of its class is CS, then:

  • If the class CS does not exist in the current database or if CS is not the name of a class in the database associated with the serialization, then an exception is raised.

    The database associated with the serialization is normally the database that contains the column. Serializations contained in work tables and in temporary tables created with "insert into #tempdb" are, however, associated with the database in which the serialization was stored originally.

  • The value of the column reference is:

    CSC.readObject(S)

    where CSC is the column reference. If the expression raises an uncaught Java exception, then an exception is raised.

    The expression yields a reference to an object in the Java VM, which is associated with the database associated with the serialization.

Java-SQL member references

Description

References a field or method of a class or class instance.

Syntax

member_reference ::=   class_member_reference |
    instance_member_reference

class_member_reference ::=  java_sql_class_name.method_name

instance_member_reference ::= instance_expression>>member_name

instance_expression ::= column_reference | variable_name
    | parameter_name | method_call | member_reference

member_name ::=  field_name | method_name

Parameters

An expression that describes a field or method of a class or object.

An expression that describes a static method of a Java-SQL class.

An expression that describes a static or dynamic method or field of a Java-SQL class instance.

A fully qualified name of a Java-SQL class in the current database.

An expression whose datatype is a Java-SQL class.

The name of a field or method of the class or class instance.

Usage

• If a member references a field of a class instance, the instance has a null value, and the Java-SQL member reference is the target of a fetch, select, or update statement, then an exception is raised.

  Otherwise, the Java-SQL member reference has the null value.

• The double angle (>>) and dot (.) qualification take precedence over any operator, such as the addition (+) or equal to (=) operator, for example:

  X>>A1>>B1 + X>>A1>>B2

  In this expression, the addition operation is performed after the members have been referenced.

• The field or method designated by a member reference is associated with the same database as that of its Java-SQL class or instance of its Java-SQL class.

  If the Java type of a member reference is one of the Java scalar types (such as boolean, byte, and so on), then the corresponding SQL datatype of the reference is obtained by mapping the Java type to its equivalent SQL type.

  If the Java type of a member reference is an object type, then the SQL datatype is the same Java object type or class.

Java-SQL method calls

Description

To invoke a Java-SQL method, which returns a single value, use the following syntax:

Syntax

method_call ::= member_reference ([parameters])
    |  new  java_sql_class_name ([parameters])

parameters ::= parameter [(, parameter)...]

parameter ::= expression

Parameters

An invocation of a static method, instance method, or class constructor. A method call can be used in an expression where a non-constant value of the method's datatype is required.

A member reference that denotes a method.

The list of parameters to be passed to the method. If there are no parameters, include empty parentheses.

Usage

• When there are methods with the same name in the same class or instance, the issue is resolved according to Java method overloading rules.

• The datatype of a method call is determined as follows:

  • If a method call specifies new, its datatype is that of its Java-SQL class.

  • If a method call specifies a member reference that denotes a type-valued method, then the datatype of the method call is that type.

  • If a method call specifies a member reference that denotes a void static method, then the datatype of the method call is SQL integer.

  • If a method call specifies a member reference that denotes a void instance method of a class, then the datatype of the method call is that of the class.

• To include a parameter in a member reference when the parameter is a Java-SQL instance associated with another database, you must ensure that the class name associated with the Java-SQL instance is included in both databases. Otherwise, an exception is raised.

• The runtime result of a method call is as follows:

  • If a method call specifies a member reference whose runtime value is null (that is, a reference to a member of a null instance), then the result is null.

  • If a method call specifies a member reference that denotes a type-valued method, then the result is the value returned by the method.

  • If a method call specifies a member reference that denotes a void static method, then the result is the null value.

  • If a method call specifies a member reference that denotes a void instance method of an instance of a class, then the result is a reference to that instance.

  • The method call and result of the method call are associated with the same database.

  • Adaptive Server does not pass the null value as the value of a parameter to a method whose Java type is scalar.