Java Developer's Guide - Oracle

8m ago
200 Views
30 Downloads
4.39 MB
312 Pages
Last View : 16d ago
Last Download : 16d ago
Upload by : Melina Bettis
Share:
Transcription

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

7Publishing Java Classes With Call Specifications7.1What Are Call Specifications?7-17.2Defining Call Specifications7-27.2.1About Setting Parameter Modes7-37.2.2About Mapping Data Types7-37.2.3Using the Server-Side Internal JDBC Driver7-57.3Writing Top-Level Call Specifications7.3.18107-87.4Writing Packaged Call Specifications7-117.5Writing Object Type Call Specifications7-137.5.1About Attributes7-147.5.2Declaring Methods7-147.5.2.1Map and Order Methods7-157.5.2.2Constructor Methods7-157.5.2.3Examples7-16Calling Stored Procedures8.19Examples7-7Calling Java from the Top Level8-18.1.1Redirecting the Output8-18.1.2Examples of Calling Java Stored Procedures From the Top Level8-28.2Calling Java from Database Triggers8-48.3Calling Java from SQL DML8-78.4Calling Java from PL/SQL8-88.5Calling PL/SQL from Java8-108.6How Oracle JVM Handles Exceptions8-10Java Stored Procedures Application Example9.1About Planning the Database Schema9-19.2Creating the Database Tables9-29.3Writing the Java Classes9-39.4Loading the Java Classes9-79.5Publishing the Java Classes9-79.6Calling the Java Stored Procedures9-9Oracle Database Java Application Performance10.1Oracle JVM Just-in-Time Compiler (JIT)10-110.1.1Overview of Oracle JVM JIT10-110.1.2Advantages of JIT Compilation10-2viii

10.1.310.2Methods Introduced in Oracle Database 11gAbout Java Memory Usage10.2.1Configuring Memory Initialization Parameters10.2.1.11112Initializing Pool Sizes within Database Templates10-210-410-410-510.2.2About Java Pool Memory10-610.2.3Displaying Used Amounts of Java Pool Memory10-710.2.4Correcting Out of Memory Errors10-810.2.5Displaying Java Call and Session Heap Statistics10-9Security for Oracle Database Java Applications11.1Network Connection Security11-111.2Database Contents and Oracle JVM Security11-211.2.1Overview of Java 2 Security Features11-311.2.2Overview of Setting Permissions11-411.2.2.1Fine-Grain Definition for Each Permission11.2.2.2Assigning General Permission Definition to Roles11-511-1811.2.3Debugging Permissions11-1911.2.4Permission for Loading Classes11-1911.2.5Customizing the Default java.security Resource11-2011.3Database Authentication Mechanisms Available with Oracle JVM11-2211.4Secure Use of Runtime.exec Functionality in Oracle Database11-22Native Oracle JVM Support for JNDI12.1Overview of Oracle JVM Support for JNDI12-112.2Requirements for Oracle JVM Support for JNDI12-112.2.112-112.2.1.1Object permissions12-212.2.1.2Persistent Storage Tables, Indexes, and Sequences12-212.2.1.3Initial Contexts and Permissions12-312.2.1.4Object and Context Default Permissions12-312.2.2Oracle Java Directory Service JNDI Name Space Provider12-312.2.2.1Directory tFactories12-412.2.2.4OJDS URL Support12-412.2.2.5Client classpath12-512.2.312.3NamespaceNamespace BrowserOJDS Command-Line Tools12.3.1ls Command12-512-612-6ix

12.3.2cd Command12-712.3.3pwd Command12-712.3.4chown Command12-712.3.5mkdir Command12-812.3.6rm Command12-912.3.7ln Command12-912.3.8mv Command12-1012.3.9chmod Command12-1012.3.10bind Command12-1112.3.11bindds Command12-1212.3.12bindurl Command12-13OJDS APIs and .aurora.jndi.ojds.OjdsURLContext12-16Schema Objects and Oracle JVM Utilities13.1Overview of Schema Objects13-113.2What and When to Load13-213.3Resolution of Schema Objects13-213.4Compilation of Schema Objects13-313.5The ojvmtc Tool13-413.5.1About the ojvmtc Tool13-513.5.2Arguments of ojvmtc Command13-513.6The loadjava Tool13-613.6.1loadjava Tool Syntax13-713.6.2loadjava Tool Argument Summary13-813.6.3loadjava Tool Argument Details13.7The dropjava Tool13-1313-1913.7.1dropjava Tool Syntax13-2013.7.2dropjava Tool Argument Summary13-2013.7.3dropjava Tool Argument Details13-2113.7.4About Dropping Resources Using dropjava Tool13-2213.8The ojvmjava Tool13-2313.8.1ojvmjava Tool Syntax13-2313.8.2ojvmjava Tool Argument Summary13-2313.8.3ojvmjava Tool Example13-2413.8.4ojvmjava Tool Functionality13-25x

1413.8.4.1ojvmjava Tool Command-Line Options13-2513.8.4.2ojvmjava Tool Shell Commands13-26Database Web Services14.1Overview of Database Web Services14-114.2About Using Oracle Database as Web Services Consumer14-114.2.1AAbout Using Oracle JVM Web Services Call-Out Utility14-214.2.1.1Architecture of Oracle JVM Web Services Call-Out Utility14-214.2.1.2Input to Oracle JVM Web Services Call-Out Utility14-414.2.1.3Output of the Oracle JVM Web Services Call-Out Utility14-614.2.1.4Calling Secure Web Service from Oracle JVM Web ServicesCall-Out Utility14-714.2.2Web Service Data Sources (Virtual Table Support)14-714.2.3Features of Oracle Database as a Web Service Consumer14-8DBMS JAVA PackageA.1longnameA-1A.2shortnameA-1A.3get compiler optionA-1A.4set compiler optionA-2A.5reset compiler optionA-2A.6resolverA-2A.7derivedFromA-2A.8fixed in instanceA-3A.9set outputA-3A.10export sourceA-4A.11export classA-4A.12export resourceA-4A.13loadjavaA-4A.14dropjavaA-5A.15grant permissionA-5A.16grant permissionA-6A.17restrict permissionA-6A.18restrict permissionA-7A.19grant policy permissionA-7A.20grant policy permissionA-8A.21revoke permissionA-8A.22disable permissionA-9A.23enable permissionA-9A.24delete permissionA-9xi

BA.25set preferenceA-10A.26runjavaA-10A.27runjava in current sessionA-10A.28set propertyA-10A.29get propertyA-11A.30remove propertyA-11A.31show propertyA-12A.32set output to sqlA-12A.33remove output to sqlA-12A.34enable output to sqlA-13A.35disable output to sqlA-13A.36query output to sqlA-13A.37set output to javaA-13A.38remove output to javaA-14A.39enable output to javaA-14A.40disable output to javaA-15A.41query output to javaA-15A.42set output to fileA-15A.43remove output to fileA-16A.44enable output to fileA-16A.45disable output to fileA-16A.46query output to fileA-16A.47enable output to trcA-17A.48disable output to trcA-17A.49query output to trcA-17A.50endsessionA-17A.51endsession and related stateA-18A.52set native compiler optionA-18A.53unset native compiler optionA-18A.54compile classA-18A.55uncompile classA-19A.56compile methodA-19A.57uncompile methodA-19A.58start jmx agentA-20A.59set runtime exec credentialsA-20DBMS JAVASCRIPT PackageB.1DBMS JAVASCRIPT OverviewB.1.1The RUN ProcedureB-1B-1xii

B.2CDBMS JAVASCRIPT Security ModelB-2Classpath Extensions and User Classloaded MetadataC.1C.2Classpath nPrefixC-1C.1.4JSERVER CPC-2C.1.5JSERVER SCHEMAcC-2C.1.6jserver:/CP general syntaxC-2User Classloaded MetadataC-3Indexxiii

List of Tables1-1Feature List of Oracle JVM1-182-1Description of Java Code and Classes Storage in Oracle Database2-42-2Definitions for the Name and Option Parameters2-82-3Example JAVA OPTIONS Table2-92-4ORA Errors2-132-5Description of Java Files2-152-6loadjava Operations on Schema Objects2-162-7Key USER OBJECT Columns2-222-8Statement Auditing Options Related to Java Schema Objects2-242-9Object Auditing Options Related to Java Schema Options2-242-10Description of the Overview Tab Fields in JConsole Interface2-393-1Command Line Argument Summary3-2set output to sql Argument Summary3-133-3set output to java Argument Summary3-167-1Legal Data Type Mappings11-1Predefined Permissions11-1411-2JServerPermission Description11-1511-3SYS Initial Permissions11-1611-4PUBLIC Default Permissions11-1711-5JAVAUSERPRIV Permissions11-1711-6JAVASYSPRIV Permissions11-1811-7JAVADEBUGPRIV Permissions11-1813-1ojvmtc Argument Summary13-513-2loadjava Argument Summary13-813-3dropjava Argument Summary13-2013-4ojvmjava Argument Summary13-2413-5ojvmjava Command Common Options13-2613-6java Argument Summary13-2813-7connect Argument Summary13-2913-8runjava Argument Summary13-2913-9jdwp Argument Summary13-3014-1Input to Oracle JVM Web Services Call-Out Utility14-414-2Output of the Oracle JVM Web Services Call-Out Utility14-63-97-3xiv

PrefaceJava is the object-oriented programming language of choice that provides platformindependence and automated storage management techniques. It enables you tocreate applications and applets. Oracle Database provides support for developing anddeploying Java applications.AudienceThe Oracle Database Java Developer's Guide is intended for both Java and non-Javadevelopers. For PL/SQL developers who are not familiar with Java programming, thismanual provides a brief overview of Java and object-oriented concepts. For both Javaand PL/SQL developers, this manual discusses the following: How Java and Database concepts merge How to develop, load, and run Java stored procedures Oracle JVM Database concepts f

2 Java Applications on Oracle Database 2.1 Database Sessions Imposed on Java Applications 2-1 2.2 Execution Control of Java Applications 2-3 2.3 Java Code, Binaries, and Resources Storage 2-3 2.4 About Java Classes Loaded in the Database 2-4 2.5 Preparing Java Class Methods for Execution 2-5 2.5.1 Compiling Java Classes 2-6