Java Developer's Guide - Oracle

Oracle DatabaseJava Developer's Guide12c Release 2 (12.2)E85766-01July 2017

Oracle Database Java Developer's Guide, 12c Release 2 (12.2)E85766-01Copyright 1999, 2017, Oracle and/or its affiliates. All rights reserved.Primary Author: Tulika DasContributors: Sheryl Maring, Rick Sapir, Michael Wiesenberg, Venkatasubramaniam Iyer, Brian Wright,Timothy Smith, Malik KalfaneContributing Authors: Tanmay Choudhury , Kuassi Mensah, Mark Jungerman, Suresh Srinivasan, ErnestTucker, Robert H Lee, Dmitry Nizhegorodov, Nataraju Neeluru, David Unietis, Paul Lo, Steve Harris, EllenBarnes, Peter Benson, Greg Colvin, Bill Courington, Matthieu Devin, Jim Haungs, Hal Hildebrand, SusanKraft, Thomas Kurian, Scott Meyer, Tom Portfolio, Dave Rosenberg, Jerry Schwarz, Harlan Sexton, Xuhua LiThis software and related documentation are provided under a license agreement containing restrictions onuse and disclosure and are protected by intellectual property laws. Except as expressly permitted in yourlicense agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify,license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means.Reverse engineering, disassembly, or decompilation of this software, unless required by law forinteroperability, is prohibited.The information contained herein is subject to change without notice and is not warranted to be error-free. Ifyou find any errors, please report them to us in writing.If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it onbehalf of the U.S. Government, then the following notice is applicable:U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software,any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are"commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agencyspecific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of theprograms, including any operating system, integrated software, any programs installed on the hardware,and/or documentation, shall be subject to license terms and license restrictions applicable to the programs.No other rights are granted to the U.S. Government.This software or hardware is developed for general use in a variety of information management applications.It is not developed or intended for use in any inherently dangerous applications, including applications thatmay create a risk of personal injury. If you use this software or hardware in dangerous applications, then youshall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure itssafe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of thissoftware or hardware in dangerous applications.Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks oftheir respective owners.Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks areused under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron,the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced MicroDevices. UNIX is a registered trademark of The Open Group.This software or hardware and documentation may provide access to or information about content, products,and services from third parties. Oracle Corporation and its affiliates are not responsible for and expresslydisclaim all warranties of any kind with respect to third-party content, products, and services unless otherwiseset forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not beresponsible for any loss, costs, or damages incurred due to your access to or use of third-party content,products, or services, except as set forth in an applicable agreement between you and Oracle.

ContentsPrefaceAudiencexvDocumentation AccessibilityxvRelated DocumentsxvConventionsxviChanges in This Release for Oracle Database Java Developer'sGuideChanges in Oracle Database 12c Release 2 (12.2.0.1)1xviiIntroduction to Java in Oracle Database1.1Overview of Java1.1.11.21.3Java and Object-Oriented Programming ncapsulation1-41.1.1.6Polymorphism1-41.1.2Key Features of the Java Language1-51.1.3Java Virtual Machine1-61.1.4Java Class Hierarchy1-8About Using Java in Oracle Database1-91.2.1Java and RDBMS: A Robust Combination1.2.2About Multithreading1-101.2.3Memory Spaces Management1-111.2.4Footprint1-121.2.5Performance of an Oracle JVM1-131.2.6Dynamic Class Loading1-15Overview of Oracle JVM1.3.1Process Area1-91-151-16iii

Java session initialization, duration and entrypoints1-161.3.3The GUI1-171.3.4The IDE1-171.4Feature List of Oracle JVM1-171.5Main Components of Oracle JVM1-181.621.3.21.5.1Library 5.4Class Loader1-201.5.5Verifier1-201.5.6Server-Side JDBC Internal Driver1-201.5.7Server-Side SQLJ Translator1-211.5.8System Classes1-21Java Programming in Oracle Database1-211.6.1Java in Database Application Development1-211.6.2Java Programming Environment Usage1-221.6.3Java Stored Procedures1-221.6.4PL/SQL Integration and Oracle RDBMS Functionality1-231.6.4.1JDBC Drivers1-231.6.4.2SQLJ1-241.6.5Development Tools1-241.6.6Internet Protocol Version 6 Support1-241.7Support for Java 81-251.8Memory Model for Dedicated Mode Sessions1-25Java Applications on Oracle Database2.1Database Sessions Imposed on Java Applications2-12.2Execution Control of Java Applications2-32.3Java Code, Binaries, and Resources Storage2-32.4About Java Classes Loaded in the Database2-42.5Preparing Java Class Methods for Execution2-52.5.1Compiling Java Classes2-62.5.1.1Compiling Source Through javac2-72.5.1.2Compiling Source Through the loadjava Tool2-72.5.1.3Compiling Source at Run Time2-72.5.1.4Specifying Compiler Options2-72.5.1.5Recompiling Source Programs Automatically2-92.5.2Overview of Resolving Class Dependencies2-102.5.2.1Allowing References to Nonexistent Classes2-112.5.2.2Bytecode Verifier2-12iv

2.5.3Logging in Oracle JVM2-132.5.4Overview of Loading Classes Using the loadjava Tool2-152.5.4.1About Sharing of Metadata for User Classloaded Classes2-172.5.4.2Defining the Same Class Twice2-172.5.4.3About Designating Database Privileges and JVM Permissions2-182.5.4.4About Loading JAR or ZIP Files2-182.5.4.5Database Resident JARs2-182.5.5Overview of Granting Execute Rights2-192.5.6Overview of Controlling the Current User2-202.5.7Overview of Checking Java Uploads2-222.5.8About Publishing Java Methods Loaded in the Database2-232.5.9Overview of Auditing Java Classes Loaded in the Database2-232.6User Interfaces on the Server2-252.7Shortened Class Names2-262.8Class.forName() in Oracle Database2-262.8.1Supply ClassLoader in Class.forName()2-272.8.2Supply Class and Schema Names to classForNameAndSchema()2-282.8.3Supply Class and Schema Names to lookupClass()2-292.8.4Supply Class and Schema Names when Serializing2-292.8.5Class.forName Example2-292.9About Managing Your Operating System Resources2-302.9.1Overview of Operating System Resources2-312.9.2Garbage Collection and Operating System Resources2-312.10About Using the Runtime.exec Functionality in Oracle Database2-332.11Managing Your Applications Using JMX2-332.11.1Overview of JMX2-332.11.2Enabling and Starting JMX in a Session2-342.11.3Setting Oracle JVM JMX Defaults and Configurability2-352.11.4Examples of SQL calls to dbms java.start jmx agent2-362.11.5Using JConsole to Monitor and Control Oracle JVM2-372.11.5.1Using the jconsole Command2-372.11.5.2About Using the JConsole interface2-382.11.5.3About Viewing Oracle JVM Summary Information2-382.11.5.4About Monitoring Memory Consumption2-402.11.5.5About Monitoring Thread Use2-422.11.5.6About Monitoring Class Loading2-422.11.5.7About Monitoring and Managing MBeans2-432.11.5.8About Viewing VM Information2-462.11.5.9The OracleRuntime MBean2-472.11.5.102.11.6Memory ThresholdsImportant Security Notes2-502-52v

2.11.72.122-53Thread Life Cycle2-542.12.2System.exit(), OracleRuntime.exitSession(), andOracleRuntime.exitCall()2-55Shared Servers Considerations2-562.13.1End-of-Call Migration2-562.13.2Oracle-Specific Support for End-of-Call Optimization2-572.13.3The EndOfCallRegistry.registerCallback() Method2-602.13.4The EndOfCallRegistry.runCallbacks() Method2-602.13.5The Callback Interface2-612.13.6The Callback.act() method2-612.13.7Operating System Resources Affected Across Calls2-61Calling Java Methods in Oracle Database3.14Overview of Threading in Oracle Database2-522.12.12.133Shared Server Limitations for JMXInvoking Java Methods3-13.1.1Using PL/SQL Wrappers3-13.1.2About JNI Support3-33.1.3About Utilizing SQLJ and JDBC with Java in the Database3-33.1.3.1Using JDBC3-43.1.3.2Using SQLJ3-43.1.3.3Example Comparing JDBC and SQLJ3-63.1.3.4SQLJ Strong Typing Paradigm3-73.1.3.5Translating a SQLJ Program3-83.1.3.6Interaction with PL/SQL3-83.1.4About Using the Command-Line Interface3.1.5Overview of Using the Client-Side Stub3-83-103.1.5.1Using the Default Service Feature3-113.1.5.2Testing the Default Service with a Basic Configuration3-113.2How To Tell Whether You Are Running on the Server3-123.3About Redirecting Output on the Server3-12Java Installation and Configuration4.1Initializing a Java-Enabled Database4.1.14.1.24-1Configuring the Oracle JVM Option within the Oracle DatabaseTemplate4-1Modifying an Existing Oracle Database to Include Oracle JVM4-14.2Configuring Oracle JVM4-24.3The DBMS JAVA Package4-24.4Enabling the Java Client4-2vi

5Installing Java SE on the Client4-34.4.2Setting Up Environment Variables4-34.5Two-Tier Duration for Java Session State4-44.6About Setting System Properties4-4Introduction to Nashorn JavaScript Engine5.164.4.1About Using Nashorn JavaScript Engine5-15.1.1Loading JavaScript Code into a Schema5-25.1.2How to run JavaScript in Oracle JVM5-35.1.2.1Using the DBMS JAVASCRIPT.RUN PL/SQL Procedure5-35.1.2.2Using the DbmsJavaScript Java Class5-35.1.2.3Using the Standard javax.script Java Package5-45.2JavaScript Data Access using JDBC5-65.3REST Enable Your JavaScript Application5-9Developing Java Stored Procedures6.16.26.36.4Stored Procedures and Run-Time Contexts6-16.1.1Functions and Procedures6-26.1.2Database Triggers6-26.1.3Object-Relational Methods6-2Advantages of Stored Procedures6-36.2.1Performance6-36.2.2Productivity and Ease of rity6-4Running Java Stored Procedures6-56.3.1Creating or Reusing the Java Classes6-66.3.2Loading and Resolving the Java Classes6-66.3.3Publishing the Java Classes6-66.3.4Calling the Stored Procedures6-7Debugging Java Stored Procedures6-76.4.1Prerequisites for Debugging Java Stored Procedures6-86.4.2Debugging Java Stored Procedures Using the jdb Debugger6-86.4.3Debugging Java Stored Procedures Using JDeveloper6-10vii