CHAPTER 44. Java Stored Procedures

Transcription

1 CHAPTER 44 Java Stored Procedures

2 752 Oracle Database 12c: The Complete Reference You can write stored procedures, triggers, object type methods, and functions that call Java classes. In this chapter, you learn about a sample set of Java procedures, along with the commands required to execute a procedure. To get the most from this chapter, you should already be familiar with Java structures (refer to Chapter 42) and Java classes and JDBC (Chapter 43). You should also be familiar with the basic syntax and usage of stored procedures (refer to Chapter 35). To focus on the database access operations of the Java classes, the example in this chapter is brief. The following class, called BookshelfDML, contains methods to insert and delete records from the BOOKSHELF table. In this example, the calculation of the area is not performed; rather, all required values are supplied during the INSERT. The following listing shows the BookshelfDML.java class file: import java.sql.*; import java.io.*; import oracle.jdbc.*; public class BookshelfDML { public static void insertbookshelf (String title, String publisher, String categoryname, String rating) throws SQLException { String sql = "INSERT INTO BOOKSHELF VALUES (?,?,?,?)"; try { Connection conn = DriverManager.getConnection("jdbc:default:connection:"); PreparedStatement pstmt = conn.preparestatement(sql); pstmt.setstring(1, title); pstmt.setstring(2, publisher); pstmt.setstring(3, categoryname); pstmt.setstring(4, rating); pstmt.executeupdate(); pstmt.close(); } catch (SQLException e) {System.err.println(e.getMessage());} } public static void updatebookshelf (String rating, String title) throws SQLException { String sql = "UPDATE BOOKSHELF SET Rating =? " + "WHERE Title =? "; try { Connection conn = DriverManager.getConnection("jdbc:default:connection:"); PreparedStatement pstmt = conn.preparestatement(sql); pstmt.setstring(1, rating); pstmt.setstring(2, title); pstmt.executeupdate(); pstmt.close(); } catch (SQLException e) {System.err.println(e.getMessage());} }

3 CHAPTER 44: Java Stored Procedures 753 public static void deletebookshelf (String title) throws SQLException { String sql = "DELETE FROM BOOKSHELF WHERE TITLE =?"; try { Connection conn = DriverManager.getConnection("jdbc:default:connection:"); PreparedStatement pstmt = conn.preparestatement(sql); pstmt.setstring(1, title); pstmt.executeupdate(); pstmt.close(); } catch (SQLException e) {System.err.println(e.getMessage());} } } The BookshelfDML.java file defines the BookshelfDML class. Within the BookshelfDML class, there are separate methods for processing INSERTs, UPDATEs, and DELETEs. In each of the method specifications, the datatypes for the BOOKSHELF table s related columns are specified (in this example, they are all VARCHAR2 datatypes). These parameters use the datatypes provided as part of Oracle s class libraries. If you use the standard Java datatypes, you may encounter datatype-related problems during the class execution. The next part of the INSERT method inserts the values into the BOOKSHELF table: string sql = "insert into bookshelf values (?,?,?,?)"; The four variables are defined via setstring (setint would be used for integers): pstmt.setstring(1, title); pstmt.setstring(2, publisher); pstmt.setstring(3, categoryname); pstmt.setstring(4, rating); Note that the variable names are case sensitive they must exactly match the names declared earlier. The DELETE method is very similar in structure. Its SQL statement is string sql = "delete from bookshelf where title =?"; Note that no part of the class creates a connection to the database, in contrast with the examples in Chapter 43. The connection used to invoke this class will provide the connection context for the class s methods. You can verify that the class compiles properly by processing it via the Java compiler. Note that this step will not validate your SQL: javac BookshelfDML.java This step should complete successfully. If you encounter errors during this compilation step, check your environment configuration (see the README file supplied with your Oracle software) and your class file.

4 754 Oracle Database 12c: The Complete Reference Loading the Class into the Database You can use the loadjava utility to load the class into the database. The syntax for the loadjava utility is as follows: loadjava {-user -u} [-option_name -option_name...] filename filename... The options available for the loadjava utility are shown in Table For example, to load the BookshelfDML.java file into the Practice schema in an instance named orcl, you can use the following command: loadjava -user -verbose BookshelfDML.java NOTE Depending on your specific configuration, you may need to use the -encoding argument as well. You should see a series of comments related to the loading of the class into the database. If any errors are reported, the load will not complete. NOTE The name of the class should not match the name of any of the existing objects in your schema. Argument -casesensitivepub -cleargrants -debug -definer -dirprefix prefix Description Publishing creates case-sensitive names. Unless the names are already all uppercase, you will usually have to quote the names in PL/SQL. The -grant option causes the loadjava tool to grant EXECUTE privileges to classes, sources, and resources. However, it does not cause it to revoke any privileges. If -cleargrants is specified, then the loadjava tool revokes any existing grants of execute privilege before it grants the EXECUTE privilege to the users and roles specified by the -grant operand. For example, if the intent is to have execute privilege granted to only SCOTT, then the proper options are -grant scott -cleargrants This turns on SQL logging. By default, class schema objects run with the privileges of their invoker. This option confers definer privileges on classes instead. This option is conceptually similar to the UNIX setuid facility. For any files or JAR entries that start with prefix, this prefix is deleted from the name before the name of the schema object is determined. For classes and sources, the name of the schema object is determined by their contents. Therefore, this option only affects resources. TABLE Loadjava Utility Options

5 CHAPTER 44: Java Stored Procedures 755 Argument -encoding filenames -fileout file -force -genmissing -genmissingjar jar_file -grant Description This argument identifies the source file encoding for the compiler, overriding the matching value, if any, in JAVA$OPTIONS. Values are the same as for the javac -encoding option. If you do not specify an encoding on the command line or in JAVA$OPTIONS, then the encoding is assumed to be the value returned by: System.getProperty("file.encoding"); This option is relevant only when loading a source file. You can specify any number and combination of.java,.class,.sqlj,.ser,.jar,.zip, and resource filename arguments. This displays all messages to the designated file. This argument forces files to be loaded, even if they match digest table entries. This argument determines what classes and methods are referred to by the classes that the loadjava tool is asked to process. Any classes not found in the database or file arguments are called missing classes. This option generates dummy definitions for missing classes containing all the referred methods. It then loads the generated classes into the database. This processing happens before the class resolution. Because detecting references from source is more difficult than detecting references from class files, and because source is not generally used for distributing libraries, the loadjava tool will not attempt to do this processing for source files. The schema in which the missing classes are loaded will be the one specified by the -user option, even when referring classes are created in some other schema. The created classes will be flagged so tools can recognize them. In particular, flagging is needed so the verifier can recognize the generated classes. This option performs the same actions as -genmissing. In addition, it creates a JAR file, jar_file, that contains the definitions of any generated classes. This argument grants the EXECUTE privilege on loaded classes to the listed users. Any number and combination of usernames can be specified, separated by commas, but not spaces. Granting the EXECUTE privilege on an object in another schema requires that the original CREATE PROCEDURE privilege was granted via the WITH GRANT options. Note: -grant is a cumulative option. Users are added to the list of those with the EXECUTE privilege. To remove privileges, use the -cleargrants option. The schema name should be in uppercase. TABLE Loadjava Utility Options (continued)

6 756 Oracle Database 12c: The Complete Reference Argument -help -jarasresource -jarsasdbobjects -noaction -norecursivejars -nosynonym -nousage -noverify -oci -oci8 -prependjarnames Description This option displays a message on how to use the loadjava tool and its options. Instead of unpacking the JAR file and loading each class within it, this argument loads the whole JAR file into the schema as a resource. This argument indicates that JARs processed by the current loadjava tool command should be stored in the database as database resident JARs. This argument indicates that no action should be taken on the files. Actions include creating the schema objects, granting execute permissions, and so on. The normal use of this argument is within an option file to suppress creation of specific classes in a JAR. When used on the command line, unless overridden in the option file, it will cause the loadjava tool to ignore all files, except that JAR files will still be examined to determine if they contain a META-INF/loadjava-options entry. If so, then the option file is processed. The -action option in the option file overrides the -noaction option specified on the command line. This argument treats JAR files contained in other JAR files as resources. This is the default behavior. This option is used to override the -recursivejars option. This default behavior does not create a public synonym for the classes. This option overrides the -synonym option. This option suppresses the usage message that is given if no option is specified or if the -help option is specified. This argument sets the classes to be loaded without bytecode verification. oracle.aurora.security.jserverpermission(verifier) must be granted to use this option. To be effective, this option must be used in conjunction with -resolve. This option directs the loadjava tool to communicate with the database using the JDBC Oracle Call Interface (OCI) driver. -oci and -thin are mutually exclusive. If neither is specified, then -oci is used by default. Choosing -oci implies the syntax of the -user value. You do not need to provide the URL. This option is used with the -jarsasdbobjects option. This option enables classes with the same names coming from different JARs to coexist in the same schema. It does this by prefixing a version of the name of the JAR to the class name to produce a unique name for the database object. TABLE Loadjava Utility Options (continued)

7 CHAPTER 44: Java Stored Procedures 757 Argument -proxy host:port -publish package -pubmain number -recursivejars -resolve -resolveonly Description If you do not have physical access to the server host or the loadjava client for loading classes, resources, and Java source, you can use an HTTP URL with the loadjava tool to specify the JAR, class file, or resource, and then load the class from a remote server. host is the host name or address, and port is the port the proxy server is using. The URL implementation must be such that the loadjava tool can determine the type of file to load that is, JAR, class, resource, or Java source. For example: loadjava -u scott -r -v -proxy proxy_server: /the/path/my.jar Password: password When the URL support is used inside the server, you should have proper Java permissions to access the remote source. The URL support also includes ftp: and file: URLs. The package is created or replaced by the loadjava tool. Wrappers for the eligible methods are defined in this package. Through the use of option files, a single invocation of the loadjava tool can be instructed to create more than one package. Each package undergoes the same name transformations as the methods. A special case applied to methods with a single argument, which is of type java.lang.string. Multiple variants of the SQL procedure or function are created, each of which takes a different number of arguments of type VARCHAR. In particular, variants are created taking all arguments up to and including number. The default value is 3. This option applies to main, as well as any method that has exactly one argument of type java.lang.string. Normally, if the loadjava tool encounters an entry in a JAR with a.jar extension, it loads the entry as a resource. If this option is specified, then the loadjava tool processes contained JAR files as if they were top-level JAR files. That is, it reads their entries and loads classes, sources, and resources. This option compiles, if necessary, and resolves external references in classes after all classes on the command line have been loaded. If you do not specify the -resolve option, the loadjava tool loads files, but does not compile or resolve them. This tells the loadjava tool to skip the initial creation step. It will still perform grants, resolves, create synonyms, and so on, however. TABLE Loadjava Utility Options (continued)

8 758 Oracle Database 12c: The Complete Reference Argument -resolver -schema -stdout -stoponerror -synonym -tableschema schema -thin -unresolvedok -user -verbose Description This option specifies an explicit resolver specification, which is bound to the newly loaded classes. If -resolver is not specified, then the default resolver specification, which includes current user s schema and PUBLIC, is used. This argument designates the schema where schema objects are created. If not specified, then the -user schema is used. To create a schema object in a schema that is not your own, you must have the CREATE PROCEDURE or CREATE ANY PROCEDURE privilege. You must have CREATE TABLE or CREATE ANY TABLE privilege. Finally, you must have the JServerPermission loadlibraryinclass for the class. This option directs the output to stdout, rather than to stderr. Normally, if an error occurs while the loadjava tool is processing files, it issues a message and continues to process other classes. This option makes it stop when an error occurs. In addition, it reports all errors that apply to Java objects and are contained in the USER_ERROR table of the schema in which classes are being loaded, except that it does not report ORA errors. These are errors that are generated when a class cannot be resolved because a referred class could not be resolved. Therefore, these errors are a secondary effect of whatever caused a referred class to be unresolved. This argument creates a PUBLIC synonym for loaded classes, making them accessible outside the schema into which they are loaded. To specify this option, you must have the CREATE PUBLIC SYNONYM privilege. If -synonym is specified for source files, then the classes compiled from the source files are treated as if they had been loaded with -synonym. This option creates the loadjava tool internal tables within the specified schema, rather than in the Java file destination schema. This option directs the loadjava tool to communicate with the database using the JDBC Thin driver. Choosing -thin implies the syntax of the -user value. You do need to specify the appropriate URL through the -user option. When combined with -resolve, this argument ignores unresolved errors. This argument specifies a username, password, and database connection string. The files will be loaded into this database instance. This argument directs the loadjava tool to display detailed status messages while running. Use the -verbose option to learn when the loadjava tool does not load a file because it matches a digest table entry. TABLE Loadjava Utility Options (continued)

9 CHAPTER 44: Java Stored Procedures 759 The AreasDML class is now loaded into the database. During loading, Oracle will create multiple tables and Java objects within your schema. NOTE You can load Java files manually from local BFILE or LOB columns via the CREATE JAVA [source class resource ] commands. If you are running your database on a stand-alone server and you have not defined a service name for the database, you need to specify a full connection specification for the loadjava program call. The format is loadjava -user practice/practice@localhost:1521:orcl -v BookshelfDML.java How to Access the Class Now that the BookshelfDML class has been loaded into the database, you must create a procedure to call each of the methods. The CREATE PROCEDURE command in the following listing creates a procedure called InsertBookshelfViaJava: create or replace procedure InsertBookshelfViaJava (title varchar2, publisher varchar2, category_name varchar2, rating varchar2 ) as language java name 'BookshelfDML.insertBookshelf(java.lang.String, java.lang.string, java.lang.string, java.lang.string)'; / This brief procedure has four parameters the four columns of the BOOKSHELF table. Its LANGUAGE JAVA clause tells Oracle that the procedure is calling a Java method. The name of the method is specified in the NAME clause (be consistent with your use of capital letters). The formats for the Java method call are then specified. A separate procedure deletes the BOOKSHELF table s records via a method call: create or replace procedure DeleteBookshelfViaJava (Title varchar2 ) as language java name 'BookshelfDML.deleteBookshelf(java.lang.String)'; / A third procedure update the RATING value based on TITLE: create or replace procedure UpdateBookshelfViaJava (rating varchar2, title varchar2 ) as language java name 'BookshelfDML.updateBookshelf(java.lang.String, java.lang.string)'; /

10 760 Oracle Database 12c: The Complete Reference Now, go into SQL*Plus and use the CALL command to execute the Java classes: call InsertBookshelfViaJava('TEST','TESTPub','ADULTNF','2'); You ll see this response: Call completed. Instead of using CALL, you can execute the procedure within a PL/SQL block: begin InsertBookshelfViaJava('TEST','TESTPub','ADULTNF','2'); end; / The CALL command passes the column values as parameters to the InsertBookshelfViaJava stored procedure. It formats them according to the specifications in the NAME clause and passes them to the BookshelfDML.insertBookshelf method. That method uses your current connection to execute its commands, and the row is inserted. Most of these libraries and classes will not have been loaded yet within the database. That s a lot of steps to go through, so performance will be affected the first time you run the Java stored procedure, but subsequent executions will be much faster. You can verify its success by querying the BOOKSHELF table: column Title format a10 select * from bookshelf where title like 'TEST'; TITLE PUBLISHER CATEGORYNAME RA TEST TESTPub ADULTNF 2 You can update the rating via UpdateBookshelfViaJava: begin UpdateBookshelfViaJava('3','TEST'); end; / select * from bookshelf where title like 'TEST'; TITLE PUBLISHER CATEGORYNAME RA TEST TESTPub ADULTNF 3 And you can delete that record via a call to DeleteBookshelfViaJava: begin DeleteBookshelfViaJava('TEST'); end; / select * from BOOKSHELF where Title like 'TEST'; no rows selected

11 CHAPTER 44: Java Stored Procedures 761 The call to DeleteBookshelfViaJava will complete much faster than the call to InsertBookshelfViaJava because your Java libraries will have been loaded the first time you executed InsertBookshelfViaJava. If your insert is not acceptable for example, if you attempt to insert a character string into a NUMBER datatype column Oracle will display an error. When debugging Java stored procedures, you can call System.err.println from within your Java code, as shown in the BookshelfDML.java listing earlier in this chapter. To display the output within your SQL*Plus session, you must first execute the following commands: set serveroutput on call dbms_java.set_output(10000); Calling DBMS_JAVA.SET_OUTPUT redirects the output of System.out.println to DBMS_ OUTPUT.PUT_LINE. Calling Java Stored Procedures Directly Oracle provides an application programming interface (API) to support direct invocation of static Java stored procedures. The classes for this method are found in the oracle.jpub.reflect package, so you must import this package into your client-side code. The Java interface for the API is public class Client { public static String getsignature(class[]); public static Object invoke(connection, String, String, String, Object[]); public static Object invoke(connection, String, String, Class[], Object[]); } When accessed via this API, the procedures arguments cannot be OUT or IN OUT. Returned values must all be part of the function result. Note that the method invocation uses invoker s rights. See the Java developer s guides that accompany the Oracle software installation for further details on the API. Where to Perform Commands The BookshelfDML example provides an overview of the process of implementing Java stored procedures. Suppose you now want to make the procedures more complex, involving additional tables and calculations. As shown in previous chapters, you can perform those calculations either in Java or in PL/SQL. Your choice of a platform and language for your data processing impacts your performance. In general, you pay a performance penalty the first time you execute a Java stored procedure (as the classes are loaded), but subsequent executions will not pay the same penalty. If you repeatedly execute the same commands, the performance impact of the first execution is minimal. Logging out and logging back in impacts your performance, but not nearly as much as executing a procedure the first time. When you use Java stored procedures, be aware of the way in which the application interacts with Oracle. If your users frequently log out and log back in, they will pay a performance penalty the first time they execute the procedure following each

12 762 Oracle Database 12c: The Complete Reference login. Furthermore, the first execution of the procedure following a database startup will pay the most severe performance penalty. The performance impact of these actions must be taken into account during the design stage of your application development. Here are some tips to reduce the performance penalties associated with the Java stored procedure calls: Execute each Java stored procedure following database startup. In the case of the BookshelfDML example, this may involve inserting and deleting a test record following each startup. Reduce the number of short-term database connections (for example, by connection pooling). Perform most of your direct database manipulation via standard SQL and PL/SQL. Java is an appropriate technology to use for many computational processes and for display manipulation. In general, SQL and PL/SQL are slightly more efficient than Java for database connections and data manipulation. However, the performance of Java within Oracle makes it a strong alternative to PL/SQL; the primary source of the performance penalty for Java stored procedures is the time required to go through the PL/SQL wrapper. When designing applications that integrate Java, SQL, and PL/SQL, focus on using each language for the functions that it performs best. If your code involves many loops and manipulations of data, Java may outperform PL/SQL. The costs of using Java for Java object creation and the PL/SQL header interaction may be offset by the improved performance Java yields during the actual work. Note that the compiled native PL/SQL first available in Oracle Database 11g should provide a strong alternative to Java from a performance perspective. In general, actions that involve selecting data from the database and manipulating it are best handled by PL/SQL and SQL. Computations on the selected data may be processed faster by Java. In your application design, be sure to use the proper tool for the proper function, and avoid unnecessary performance penalties.