Software: Apache. PHP/5.5.15 uname -a: Windows NT SVR-DMZ 6.1 build 7600 (Windows Server 2008 R2 Enterprise Edition) i586 SYSTEM Safe-mode: OFF (not secure) E:\oracle\product\10.2.0\client_2\sqlj\ drwxrwxrwx |
Viewing file: READMEJPub.txt (27.14 KB) -rw-rw-rw- Select action/file-type: (+) | (+) | (+) | Code (+) | Session (+) | (+) | SDB (+) | (+) | (+) | (+) | (+) | (+) | Release Notes for JPublisher (JPub) 10.1.0.2.0 This file contains important information about version 10.1.0.2.0 of the Java Publisher utility, or JPub for short. JPub generates Java source code that makes it easy for you to represent Oracle Object types and PL/SQL packages in your Java programs. JPub is documented in the _Oracle 9i JPublisher User's Guide_. Some of the comments in this README file presume that you have seen the JPub documentation. These notes are divided into the following sections: 1. HOW TO INSTALL AND INVOKE JPUB 2. SEVERAL FREQUENTLY ASKED QUESTIONS ABOUT JPUB 3. NEW FEATURES IN THIS VERSION 4. BUGS FIXED IN JPUB 5. KNOWN BUGS AND RESTRICTIONS 1: INSTALL AND INVOKE JPUB JPub is a Java program. It is shipped with Oracle SQLJ. If you have installed SQLJ, you have installed JPub. Currently, JPub requires SQLJ because: * JPub generates .sqlj code as intermediate files, which will be compiled into .java code by the SQLJ translator * JPub-generated code requires SQLJ runtime. In the future, JPub may be decoupled from SQLJ, in that JPub would generate .java code that does not depend on SQLJ runtime. JPub communicates with the database via JDBC. To run JPub, you must also install a JDBC driver. If you are using Oracle objects, an Oracle 9.2.0 JDBC driver is recommended, and an Oracle 8.1.x JDBC driver is required. By default, JPub communicates with the Oracle database using the Oracle JDBC OCI driver, but you may select another driver, such as the Oracle "thin" driver, by setting the -url command-line parameter. For information on installing JPublisher and JDBC, see: * the Oracle 10g SQLJ Developer's Guide and Reference * the Oracle 10g JDBC Developer's Guide and Reference * the Oracle 10g JPublisher User's Guide To install JPub, follow the JPublisher installation steps, as described in the JPublisher User's Guide. Here is a summary. Let ORACLE_HOME be the location into which your Oracle products have been installed. 1.1. INVOKE JPUB VIA jpub The installation process will create a script file (a shell script on Unix platforms, and a .bat script on Windows platforms) that directly includes references to the Java JRE, the JDBC driver, and the SQLJ translator that has been installed. You should be able to just invoke this script by typing jpub on the command line followed by zero or more arguments. If you do not provide any arguments, jpub will display information about the available command-line arguments. The "jpub" script uses an installation-specific CLASSPATH, i.e., the installation process hardcodes the CLASSPATH environement variable for JPublisher in the "jpub" script based on the JDK location detected during installation. 1.2. INVOKE JPUB VIA oracle.jpub.Doit If you have downloaded JPublisher from the Oracle website as part of the SQLJ product, then the "jpub" script will not have been automatically created and customized for you. In this case you should perform the steps outlined below. * Include in your environment variable CLASSPATH the appropriate o Oracle JDBC driver for your environment: o ORACLE_HOME/jdbc/lib/classes12.jar (for JDK 1.2 and 1.3), or o ORACLE_HOME/jdbc/lib/ojdbc14.jar (for JDK 1.4). o On Windows platforms, these file names are written: o ORACLE_HOME\jdbc\lib\classes12.jar (for JDK 1.2 and 1.3), or o ORACLE_HOME\jdbc\lib\ojdbc14.jar (for JDK 1.4), or * Include in your CLASSPATH the file ORACLE_HOME/sqlj/lib/translator.jar. The translator.jar file contains the .class files for both SQLJ and JPub. * Include in your CLASSPATH the file ORACLE_HOME/sqlj/lib/runtime12.jar (for JDK 1.2 or later). The runtime files contains runtime .class files for both SQLJ and JPub. Alternatively, you can use ORACLE_HOME/sqlj/lib/runtime.jar (this setting would be required if you are using an 8.1.7 or older JDBC driver). * Make sure that you can execute commands in the directory ORACLE_HOME/bin (or ORACLE_HOME\bin). In Unix environments, this is accomplished by including the directory ORACLE_HOME/bin in your PATH environment variable. The ORACLE_HOME/bin directory includes a wrapper script or executable to simplify the invocation of SQLJ. To invoke JPublisher, use the command java oracle.jpub.Doit followed by zero or more command-line arguments. The command above has the same effect as the "jpub" command mentioned in Section 1.1, except that, with the command above, JPublisher picks up the CLASSPATH setting in your environment, while in the Section 1.1 case, the CLASSPATH variable picked by JPublisher is pre-defined during installation. 1.3 AFTER GENERATION To use classes generated by JPub: * Include the file ORACLE_HOME/jdbc/lib/ojdbc14.jar (for JDK 1.4), the file ORACLE_HOME/jdbc/lib/classes12.jar (for JDK 1.2 and JDK 1.3), and ORACLE_HOME/sqlj/lib/runtime12.jar in your CLASSPATH. * Include in your CLASSPATH the directories of the packages containing the .class files for the classes generated by JPub. Now you are ready to run JPub-generated code. 1.4 WEBSERVICES CALLOUT SETUP JPublisher can generate webservices client and its PL/SQL wrapper, to support webservice invocation inside the database. This functionality, also called webservices callout, requires the following extra setup steps. First, download the webservice callout utility for 10g from the OTN website below. http://otn.oracle.com/tech/webservices/database.html Second, extract downloaded archive under ORACLE_HOME. The utl_dbws.jar and utl_dbws_jserver.jar file will be added to the directory ORACLE_HOME/sqlj/lib Third, load the utl_dbws_jserver. jar file into the SYS schema or into the schema where the webservice client will be invoked. For instance, to load that jar file to SYS, use the loadjava command below. loadjava -u sys/change_on_install -r -v -f -s -grant public utl_dbws_jserver.jar 2. JPUB FREQUENTLY ASKED QUESTIONS Question: Why can't I write Java classes by hand for my object types and packages? You can. However, this is error-prone. A Java class that represents an Oracle object type in a JDBC program must implement the oracle.sql.ORAData interface or the java.sql.SqlData interface. A Java class that represents an Oracle object type in a SQLJ program must also name the object type in a declaration within the class of the form public static final String _SQL_NAME = "<name of object type>"; Code generated by JPub handles these tasks for you. In addition, for both object types and PL/SQL packages, JPub generates code to handle the details of argument passing and method invocation when server methods are invoked. Question: I want to add some methods to a class generated by JPub. Should I edit the class generated by JPub, or write a new class that extends the one generated by JPub? If you edit the class generated by JPub, and at some time in the future you need to run JPub again to regenerate the class, you will have to save the changes you made and reinsert them by hand. It is probably more convenient for you use subclasses that extend the classes generated by JPub. When you do this, you must tell JPub about the subclass you want to use with the -input file syntax SQL <type name> AS <subclass name> GENERATE <name of JPub-generated class> or you can use the command-line syntax -sql=<type name>:<subclass name>:<name of JPub-generated class> As of version 9.2, JPub even generates a first version of this subclass for you - all you need to do is edit the generated file. See your JPub documentation for more information on this feature. Question: Can I get JPub to generate a class that implements the java.sql.SqlData interface? Yes. JPub, the Oracle JDBC drivers, and Oracle SQLJ support your choice of the oracle.sql.ORAData interface or the java.sql.SqlData interface. By default, JPub generates to the oracle.sql.ORAData interface. You request java.sql.SqlData by specifying -usertypes=oracle In addition, for backwards compatibility with Oracle8i JDBC drivers, JPub can also generate to the oracle.sql.CustomDatum interface. You obtain this by using the following setting -compatible=CustomDatum Question: Can I override an option in the -props file by respecifying it on the command line? Yes, by specifying it on the command line after the -props option. Options are processed from left to right in the order in which they appear on the command line. Options in the -props file are processed when the -props option is encountered on the command line. Question: I said "jpub -user=scott/tiger" without specifying any object types or packages for JPub to translate, but JPub not complain about this. What happened? If the options -input, -sql, and -types are all absent, all types and packages in the user's schema will be translated. Question: When do I need to specify the JPub -encoding option? As a general rule, if you do not specify an -encoding option when you invoke your Java compiler, you do not need to specify an -encoding option when you invoke JPublisher. If -encoding is not specified, the value of the System property file.encoding is used. The encoding option specifies the character encoding to use for the input file generated by JPub, and for the .sqlj and .java files generated by JPub. The -encoding setting does not affect how the command line or the -props file is read. Question: I'm happy with the way JPub translates my object types to Java, but I also want to use object types in C programs. How can I accomplish this? Another Oracle utility, the Object Type Translator (OTT), translates object types to C. 3. NEW FEATURES IN JPUB The following changes were made to JPub between verstion 10.1.0.0.0 and 10.1.0.2.0. Using the "-proxywsdl" option, JPublisher can generate and load the webservice client and the corresponding PL/SQL call specification into the database, so that one can invoke the database webservice from the database. This functionality is also called webservices callout. When the option -omit-schema-names is set, JPublisher generates an additional method __setSchemaName(String) for a SQL object type. The purpose of the added method is to allow specifying the schema where the SQL object type is located at runtime. In previous JPublisher releases, with "-numbertypes=jdbc", the SMALLINT type is mapped into "short". While SMALLINT contains 32 binary bits in the database, the Java short type has 16 bits. Starting this release, SMALLINT is mapped into Java "int". For backward compatibility, JPublisher provides an option "-compatible=9i". When that setting and "-numbertypes=jdbc" is specified, JPublisher will map SMALLINT into "short", as previous JPublisher behave by default. The -methods options supports two additional setting, "overload" and "unique". The "overload" setting indicates that the method name in the generated Java program can be overloaded, for instance, "int foo(int)" and "int foo(String)". The "unique" setting means that every Java method generated is uniquely named, for instance, "int foo(int)" and "int fooiS(String)". The "-plsqlfile" option specifies the PL/SQL wrapper file generated during publishing PL/SQL stored procedure. Now the "-plsqlfile" can take second argument, a file that holds the SQL script file to drop the generated PL/SQL wrapper, for instance, -plsqlfile=my_wrapper.sql,my_dropper.sql Now JPublisher supports multiple -style options. If two mappings are defined for the same source type, the mapping appearing later takes effect. For database webservics, JPubisher provides two predefined -style templates, webservices9 and webservice10. With the setting -style=webservices9, JPublisher generates code compatible to Oracle Webservices in 10g(9.0.4) or earlier. With -style=webservices10, JPublisher generates code compatible to Oracle Webservices 10g (10.0). Previously, JPublisher does not acknowledge the CLASSPATH environment variable. Starting from this release, JPublisher picks up the CLASSPATH enviroment variable. The SQLJ translator may be desupported in future releases. The following JPublisher change and facilities strives to minimize the impact of future SQLJ desupport. In previous releases, JPublisher generates .java and .sqlj code. Starting this release, JPublisher no longer generates .sqlj code. Instead, JPublisher will generate .java code and .class file compiled from generated .java code. Note that for this release, .sqlj programs are actually generated, translated and removed. With the setting -compatible=sqlj, JPublisher will generate .sqlj as previous releases and will not translate the .sqlj program generated. Also with -compatible is set to 8i or 9i, JPublisher will also perserve the behavior of JPublisher 8i or 9i releases, thus will allow .sqlj programs to be generated. With the setting -compile=false, JPublisher will not compile generated .java program into .class files. The default setting is -compile=true. JPublisher now accepts the -classpath setting, which specifies the classpath used for compiling generated Java programs. JPublisher supports a new option, -compiler-executable, which specifies the compile executable used for compiling generated Java programs. With the setting -sqlj, JPublisher will use all the options following that "-sqlj" setting as SQLJ options to translate .sqlj programs generated into .java programs. At the end of the JPublisher command line, one can specifies .sqlj or .java programs to be translated and compiled along with JPublisher-generated code. For instance, jpub -u scott/tiger -s foo bar.java The following changes were made to JPub between verstion 9.2.3.0.0 and 10.1.0.0.0. JPublisher can publish SQL queries and DML statements via the option "-sqlstatement". SQL queries and DMLs can be published as methods in a generated Java class. Using the "-java" option, given a Java class in the server (database), JPublisher can generate a correpsonding client-side class which invokes the static methods in that Java class. Using the "-proxyclasses" option, JPublisher can create PL/SQL proxy for Java classes. A typical scenario for the "-proxyclasses" functionality is WebServices call-outs, where the web service calls originate from the database. Using the "-style" option, JPublisher can map an argument type into another type in the generated user subclass. As an example, JPublisher can map a returned ReultSet into an array of Java Beans, a XML document, or a WebRowSet. Using the "-filtermodes" and "-filtertype" options, JPublisher can prevent certain PL/SQL methods from being published. The "-sql" option is enhanced to support specifying certain methods to be or not to be published. Using the "-generatebean" option, JPublisher can make sure the generated Java classes for SQL types are Java beans. The following changes were made to JPub between verstion 9.0.2.1.0 and 9.2.3.0.0. JPublisher now can generate interfaces along with classes. For instance, the command "jpub -sql=<sqlType>:<javaClass>#<javaInterface>:<myClass>" generates, for a SQL type (<sqlType>), a java class (<javaClass>), a java interface (<javaInterface>), and a user Java class (<myClass>), where <javaInterface> defines the interface of <javaClass>. The generated interface contains the public methods in the generated class, typically those accessors methods. JPublisher 9.2 permits publishing of individual or selected top-level functions. JPublisher 9.2.3 generalizes function selection as follows: - Functions and procedures can be selected from any PL/SQL package. - The function names can end in the wildcard character "%" (the percent sign). In this case, they will match functions that begin with the same prefix. - SQL argument signatures of the functions or procedures can be specified as selection criteria. The following changes were made to JPub between version 9.0.1.0.0 and version 9.2.0.1.0. JPublisher now supports virtually all of the types that can be used by the Oracle JDBC driver. Additionally, JPublisher facilitates the use of PL/SQL types in stored procedure and object method signatures through PL/SQL conversion support. The following Oracle JDBC types are now directly supported: - NCHAR types - TIMESTAMP types - SQLJ object types - SQL opaque types; specifically SYS.XMLTYPE via oracle.xdb.XMLTypes. SQL opaque types can be supported through a predefined type correspondence or they can trigger JPublisher code generation. Native PL/SQL types can now be more easily accessed by JPublisher code through the automatic generation of PL/SQL wrapper functions and procedures in conjunction with the following mechanisms: - predefined type conversions, such as between PL/SQL BOOLEAN and Java boolean, or INTERVAL and String - user-defined mappings for PL/SQL index-by-tables in conjunction with the JDBC-OCI driver - user-defined conversion functions for mapping PL/SQL record types and tables of records to SQL object and collection types and Java - JPublisher provides improved functionality as well as flexibility in the code it generates and reduces programming effort further. - JPub generates attribute-based constructors for SQL object types. - New APIs are provided in the generated classes to convert between strongly typed Refs and to transfer connection information between objects. - Generated Java wrappers for SQL object types can be made serializable (new option -serializable) - JPub can create toString() methods that report the object value (new option -tostring) - When requesting user-subclassing of JPub-generated classes, a first version of the user classes will be automatically generated. - Inheritance hierarchies now require no initialization by the user application. - Generated files will not be clobbered unnecessarily, improving interaction with Makefile environments. - Extended syntax for JPublisher properties files permits multi-line option settings and the embedding of JPub directives in SQL scripts. - JPublisher permits publishing of individual or selected top-level functions. The following changes were made to JPub between version 8.1.7.0.0 and version 9.0.1.0.0. - JPublisher now only generates SQLJ code for an Object type if that type contains methods. Otherwise it will generate Java code by default (unless you use the option setting -methods=always). - The JPub-generated code now provides abstraction from the specifics of the JPublisher implementation. The following protected methods are provided as a replacement for the previously accessible _struct and _ctx fields: getConnection() - to obtain the JDBC connection getConnnectionContext() - to obtain the SQLJ context create(Object,Datum,int) - for re-using the superclass-provided implementation for a factory interface setFrom(Object), setValueFrom(Object) - to transfer internal state from another object User-written classes for JPublisher 8.1.7 must be rewritten to use these methods. Alternatively, you can use the backwards compatibility setting -compatible=8i. - By default JPublisher now uses SQLJ connection contexts of type sqlj.runtime.ref.DefaultContext rather than creating and using inner context classes _Ctx. This behavior can be adjusted with the -context command line option. - By default JPubllisher generates all wrapper classes into the current directory. Previously, it would generate the wrapper classes into a package hierarchy under the current directory. To get this behavior you now need to explicitly specify the setting "-dir=." - JPublisher will translate SQL Object types that stand in an inheritance relationship into a similar Java class hierarchy. In addition, JPublisher will also generate initialization code to create a type map that reflects this hierarchy. Users just need to create an instance of the leaf types to ensure that this initialization is performed. - With the setting -usertypes=oracle, JPublisher now generates Java classes that implement the interface oracle.sql.ORAData. The new command line option -compatible=CustomDatum can be used to generate classes for the backward compatible interface oracle.sql.CustomDatum. - The new JPublisher option -access permits control over the access modifier of JPublisher-generated methods, and the new option -context permits control over the class that is used for SQLJ connection context (sqlj.runtime.ref.DefaultContext by default), and also whether indiviual Java wrapper classes declare their own individual SQLJ context types or not. - JPublisher can now connected to the database with DBA authentication, using the username SYS or INTERNAL. The following changes were made to JPub between version 8.1.6.0.0 and version 8.1.7.0.0. - The following fields have been made protected in JPub-generated code for SQL object types. This provides for additional capabilites in user-written subclasses of the JPub-generated class. - _ctx - the SQLJ connection context object - _struct - the mutable struct object with the data in original SQL format - The Java keyword "null" takes on special significance when used as the Java name for mapping attributes or methods. - no method will be generated when a SQL method is mapped to null - no getter/setter methods will be generated when a SQL attribute is mapped to null 4. BUGS FIXED IN JPUB The following issues were addressed in JPublisher release 10.1.0.2.0. 3157214 When publishing PL/SQL stored procedures involving PL/SQL table on certain platforms, JPublisher may throw "Exhausted ResultSet" error and generate code that do not compile. The following issues were addressed in JPublisher release 10.1.0.0.0. 1757898 In Oracle9i release 9.0.1, the option "-methods=true" results in "Method not found" error during SQLJ translation if the published SQL object or packages contain no methods. The following issues were addressed in JPublisher release 9.2.0. 2116164 JPublisher could throw a NullPointerException when publishing top-level procedures and functions. 1757898 When you use JPublisher to generate Java code for a SQL Object type hierarchy where some classes add method definitions while others do not, JPublisher will now generate all classes into .sqlj files (unless the option -methods=false was specified). This ensures that the generated files are compatible with one another. n/a JPub now supports the following SQL argument types which are also supported by JDBC 9.2 and/or SQLJ: - OPAQUE types - SQLJ object types - TIMESTAMP types - NCHAR - NCLOB - NVARCHAR2 n/a JPub can now support the PL/SQL argument types, either automatically, or through a user-provided type conversion between the PL/SQL type and a corresponding SQL type. - BOOLEAN - record types - index-by tables The following issues were addressed in JPublisher release 9.0.1.0.0 1691446 In 8.1.7 JPublisher implicitly created SQLJ connection context instances. Unfortunately, the 8.1.7 SQLJ runtime was not able to properly free these when the object they were attached to got garbage-collected. In 9.0.1 you have four options to remedy this bug: - use JDK 1.2 and the SQLJ runtime12.jar - use the SQLJ translator option -codegen=oracle - explicitly issue setConnectionContext() on your objects - explicitly issue release() before your objects go out of scope. 1534649 JPub did not generate code for PL/SQL packages if no package body existed. This happened, for example, if the package header was created in advance of the implementation and then JPublisher was run to generate a .sqlj wrapper class for this package. 1497108 Changes on nested object attributes were not properly recognized by the JPub runtime. This resulted in lost update when the object with the modified attribute was written back to the database. 1418893 Running JPub on a single procedure or function failed to add the declaration for _ctx, so the generated SQLJ file did not compile. 1364448 JPub did not read the last line of the inputfile when that line was not terminated by LF or by CR/LF. 5. KNOWN BUGS AND RESTRICTIONS IN JPUB 2395122 When publishing a package in a 817 database, the integer type in the package is always mapped into java.math.BigDecimal, regardless of the -numbertypes setting. When -numbertypes is set to be "jdbc", integer should be mapped into the primitive java type "int". 2144086 If you see the following JPublisher warning message. Warning: Cannot determine what kind of type is XXXX. YYYY. You likely need to install SYS.SQLJUTL. The database returns: ORA-06550: line 1, column 7: PLS-00201: identifier 'SYS.SQLJUTL' must be declared ORA-06550: line 1, column 7: PL/SQL: Statement ignored then you are using JPublisher against an Oracle 9.2 database that is not Java enabled. In general you can ignore this message, unless you want to use SQL opaque types or SQLJ object type. You can get rid of this message by installing the package SQLJUTL into the SYS schema. This package is defined in the following SQL script file. [Oracle Home]/sqlj/lib/sqljutl.sql n/a JPublisher does not accept the following syntax: jpub -u scott/tiger -s TOPLEVEL:TopLevel Use instead: jpub -u scott/tiger -s TopLevel n/a The Java code that JPublisher generates to represent strongly typed instances of REFs permits you to create Java Refs using the empty constructor. However, calling getValue() or setValue() on such an instance results in a NullPointerException. You must always obtain a Java Ref instance from the database (or as an attribute of a database object). 1851361 When running JPublisher 8.1.7 against an 8.1.6 database, it may fail with an "invalid column name error. In this case JPublisher is not backwards compatible when looking up database metadata. As a workaround you can do one of the following. (1) Use the JPublisher version that came with your database. (2) Use JPublisher from Oracle 9.0.1 or later. It generally provides backward compatibility to 8i databases. JPub reports most, but not all, errors in the -input file to the user. A few errors in the -input file are not reported by JPub. These errors are listed below: * If the user requests the same Java class name for two different object types, the second class will silently overwrite the first. For example, if the -input file contains type PERSON1 as person TYPE PERSON2 as person the file person.java will be created for type PERSON1, and then will be overwritten for type PERSON2. * If the user requests the same attribute name for two different object attributes, get and set methods will be generated for both attributes without issuing a warning message. Whether or not the generated class is legal in Java depends on whether the two get methods with the same name and the two set methods with the same name have different argument types so that they may be overloaded. * If the user mentions a nonexistent object attribute in the TRANSLATE clause, it will be ignored without issuing a warning message. For example, if the -input file contains type PERSON translate X as attr1 and X is not an attribute of PERSON, no warning message will be issued. |
:: Command execute :: | |
--[ c99shell v. 1.0 pre-release build #13 powered by Captain Crunch Security Team | http://ccteam.ru | Generation time: 0.0312 ]-- |