Specifying Characteristics for an Opaque Type

The following sections provide additional information about creating an opaque type without a preexisting Java class. Details about creating an opaque type from an existing Java class begin with Creating an Opaque Type from Existing Code.

Using the methods in the UDTMetaData class, you can specify characteristics for a new opaque type. The characteristics you can specify are described on the following pages. These settings apply for new opaque types; for opaque types created from existing files, see Creating an Opaque Type from Existing Code.

You can set the following characteristics:

• The number of fields in the internal data structure that defines the opaque type
• Additional characteristics, such as data type, name, and scale, of each field in the internal structure that defines the opaque type
• The length of the opaque type
• The alignment of the opaque type
• The SQL name of the opaque type and the JAR file
• The name of the generated Java class
• Whether to keep the generated .java file

Specifying Field Count

The setFieldCount() method specifies the number of fields in the internal data structure that defines the opaque type:

public void setFieldCount(int fieldCount) throws SQLException

Specifying Additional Field Characteristics

The following methods set additional characteristics for fields in the internal data structure:

public void setFieldName (int field, String name) throws SQLException
public void setFieldType (int field, int ifxtype) throws SQLException
public void setFieldTypeName(int field, String sqltypename) throws SQLException
public void setFieldLength(int field, int length) throws SQLException

The field parameter indicates the field for which the driver should set or obtain a characteristic. The first field is 1; the second field is 2, and so forth.

The name you specify with setFieldName() appears in the Java class file. The following example sets the first field name to IMAGE.

mdata.setFieldName(1, "IMAGE");

The setFieldType() method sets the data type of a field using a constant from the file com.informix.lang.IfxTypes. For more information, see Mapping for Field Types. The following example specifies the CHAR data type for values in the third field:

mdata.setFieldType(3, com.informix.lang.IfxTypes.IFX_TYPE_CHAR); 

The setFieldTypeName() method sets the data type of a field using the SQL data type name:

mdata.setFieldTypeName(1, "IMAGE_UDT");

This method is valid only for opaque and distinct types; for other types, the driver ignores the information.

The length parameter has the following meanings, depending on the data type of the field:

Character types

Maximum length in characters

DATETIME

Encoded length

INTERVAL

Encoded length

Other data type or no type specified

Driver ignores the information

The possible values for encoded length are those in the JDBC 2.20 specification: hour to second; year to second; and year to fraction(1), year to fraction(2), up through year to fraction(5).

The following example specifies that the third (VARCHAR) field in an opaque type cannot store more than 24 characters:

mdata.setFieldLength(3, 24); 

Specifying Length

The setLength() method specifies the total length of the opaque type:

public void setLength(int length) throws SQLException

If you are creating an opaque type from an existing Java class and do not specify a length, the driver creates a variable-length opaque type. If you are creating an opaque type without an existing Java class, you must specify a length; UDT Manager creates only fixed-length opaque types in this case.

Specifying Alignment

The setAlignment() method specifies the opaque type's alignment:

public void setAlignment(int alignment)

The alignment parameter is one of the alignment values shown in the next section. If you do not specify an alignment, the database server aligns the opaque type on 4-byte boundaries.

Alignment Values

Alignment values are shown in the following table.

Specifying SQL Names

Specify SQL names with the setSQLName() and setJarFileSQLName() methods:

public void setSQLName(String name) throws SQLException
public void setJarFileSQLName(String name) throws SQLException

By default, the driver uses the name you set through the setSQLName() method as the filenames of the Java class and JAR files generated when you call the UDTManager.createUDTClass() and UDTManager.createJar() methods. For example, if you called setSQLName("circle") and then called createUDTClass() and createJar(), the class filename generated would be circle.class and the JAR filename would be circle.jar. You can specify a Java class filename other than the default by calling the setClassName() method.

The JAR file SQL name is the name as it will be referenced in the SQL CREATE FUNCTION statement the driver uses to register a UDR.

Specifying the Java Class Name

Use setClassName() to specify the Java class name:

public void setClassName(String name)throws SQLException

If you do not set a class name with setClassName(), the driver uses the SQL name of the opaque type (set through setSQLName()) as the name of the Java class and the filename of the .class file generated by the createUDTClass() method.

Specifying Java Source File Retention

Use keepJavaFile() to specify whether to retain the .java source file:

public void keepJavaFile(boolean value)

The value parameter indicates whether the createUDTClass() method should retain the .java file that it generates when it creates the Java class file for the new opaque type. The default is to remove the file. The following example specifies keeping the .java file:

mdata.keepJavaFile(true);