Oracle® Tuxedo Programming an Oracle Tuxedo Application Using Java 12C Release 1 (12.1.1)
Total Page:16
File Type:pdf, Size:1020Kb
Oracle® Tuxedo Programming an Oracle Tuxedo Application Using Java 12c Release 1 (12.1.1) June 2012 Oracle Tuxedo Programming an Oracle Tuxedo Application Using Java, 12c Release 1 (12.1.1) Copyright © 1996, 2012, Oracle and/or its affiliates. All rights reserved. This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license 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 for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you 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 on behalf of the U.S. Government, 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 agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, 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 that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services. Contents 1. Introduction to Oracle Tuxedo Java Programming Overview . .1-1 Programing Guidelines . 1-2 Tuxedo Java Server Threads and Java Class Instance Model. 1-2 Tuxedo Java Server tpsvrinit()/tpsvrdone() Handling. 1-2 tpsvrinit() Handling . 1-2 tpsvrdone() Handling . 1-3 Tuxedo Java Server tpreturn() Handling. 1-3 Tuxedo Java Server Exception Handling . 1-3 2. Programming Environment Updating the UBB Configuration File . 2-1 3. ATMI Java Server User Interfaces TuxedoJavaServer. 3-1 Oracle Tuxedo Java Context . 3-2 TJATMI Primitives for Tuxedo Java Applications. 3-2 TypedBuffers for Tuxedo Java Applications . 3-3 Limitations for Typedbuffer Support . 3-4 Get/Set Service Information . 3-4 Exception. 3-4 Trace . 3-5 Programming an Oracle Tuxedo Application Using Java i 4. Implementing Services in Oracle Tuxedo Java Server Typical Procedures . 4-1 Example: Implementing Java Service without Transaction . 4-2 Defining Java Classes . 4-2 Creating Java Server Configuration File . 4-5 Updating UBB Configuration File . 4-5 Example: Implementing Java Service with Transaction . 4-6 Defining Java Classes . 4-6 Creating Java Server Configuration File . 4-10 Updating UBB Configuration File . 4-11 5. Reference Using FML with Oracle Tuxedo Java Server . 5-1 Overview of FML . 5-1 The Oracle WebLogic Tuxedo Connector FML API . 5-2 FML Field Table Administration. 5-2 Using the DynRdHdr Property for mkfldclass32 Class . 5-3 Gaining TypedFML32 Performance Improvements . 5-5 Using VIEW with Oracle Tuxedo Java Server. 5-5 Overview of VIEW Buffers. 5-5 How to Create a VIEW Description File. 5-6 Example VIEW Description File. 5-7 How to Use the viewj Compiler . 5-8 How to Pass Information to and from a VIEW Buffer . 5-10 How to Use VIEW Buffers in JATMI Applications . 5-11 How to Get VIEW32 Data In and Out of FML32 Buffers . 5-11 ii Programming an Oracle Tuxedo Application Using Java CHAPTER 1 Introduction to Oracle Tuxedo Java Programming This topic includes the following sections: z Overview z Programing Guidelines z Tuxedo Java Server Threads and Java Class Instance Model z Tuxedo Java Server tpsvrinit()/tpsvrdone() Handling z Tuxedo Java Server tpreturn() Handling z Tuxedo Java Server Exception Handling Overview An Oracle Tuxedo service can be developed using pure Java language. The service implemented with Java language functions the same as other Tuxedo services. You can call the services advertised by the Tuxedo Java server (TMJAVASVR) using ATMI interfaces from client/ Tuxedo server, and similarly, you can call the services advertised by the Tuxedo server using TJATMI interfaces from the java-implemented service. Besides, you can call java-implemented services from any type of Tuxedo clients, such as native clients, /WS clients, and Jolt clients. It is supported to use a variety of mainstream Java technologies like TJATMI interface, JATMI TypedBuffers, POLO java object, and so on to implement Tuxedo services. Programming an Oracle Tuxedo Application Using Java 1-1 Programing Guidelines The following guidelines are basic instructions for Java service development. z Java server class, which implements Java services, should inherit the TuxedoJavaServer class; Java server class also should have a default constructor. z In Java server class, Java method, which will be advertised as Java service, should take the TPSVCINFO interface as the only input argument and should be declared to public. z Java server class should implement tpsvrinit() method, which will be called when Tuxedo Java server starts up. z Java server class should implement tpsvrdone() method, which will be called when Tuxedo Java server shuts down. z Java service could use Tuxedo Java ATMI (e.g, tpcall, tpbegin, etc). z Java service could return result to client by using tpreturn and exit by throwing exception. Tuxedo Java Server Threads and Java Class Instance Model z Tuxedo Java server uses traditional Tuxedo multithread model and must be running in multithread mode. z Once started, Tuxedo Java server creates one global object (instance) for each class defined in the configuration file and then the working threads share the global object (instance) when handling the Java service. Tuxedo Java Server tpsvrinit()/tpsvrdone() Handling tpsvrinit() Handling Users need to implement the tpsvrinit() method. Given that tpsvrinit() will be called when server starts up, it's recommended to put the class scope initialization in this method. If one class' tpsvrinit() fails, a warning message will be reported in user log and the Java server will continue its execution. 1-2 Programming an Oracle Tuxedo Application Using Java Tuxedo Java Server tpreturn() Handling tpsvrdone() Handling Users need to implement the tpsvrdone() method. Given that tpsvrdone() will be called when the server shuts down, it's recommended to put the class scope cleanup actions in this method. Tuxedo Java Server tpreturn() Handling The tpreturn() in Java service does not immediately disrupt the Java service method's execution but provide the return result to Tuxedo Java server. How does tpreturn() behave in Java service is different from how does tpreturn() behave in the existing Tuxedo system. z When a tpreturn() is called in the existing Tuxedo system, the flow control is transferred to Tuxedo automatically. z When a tpreturn() is called in Java service, statements after tpreturn() will still be executed. Users must make sure tpreturn() is the last execution statement in Java service - if not, we suggest to use a following Java return invocation after tpreturn(); otherwise, tpreturn() will not transfer the flow control to the Tuxedo system automatically. Note: The use of a Java return statement in Java service without a previous tpreturn() statement is not suggested - such use will make the Java server return TPFAIL with rcode setting 0 to the corresponding client. Tuxedo Java Server Exception Handling z Java service can throw any exception during execution and exit the Java service. In this case the Java server will return TPFAIL with rcode setting to 0 for this service to its client. z All the exception information is recorded into the $APPDIR/stderr file. Programming an Oracle Tuxedo Application Using Java 1-3 1-4 Programming an Oracle Tuxedo Application Using Java CHAPTER 2 Programming Environment This topic includes the following sections: z Updating the UBB Configuration File Updating the UBB Configuration File You need to configure the path of where the Tuxedo Java server finds the configuration file for the Java-implemented services in CLOPT. As the ATMI Java server is a multithread server, you also need to specify the limit of dispatching threads. For more information about the multithread server configuration, see Defining the Server Dispatch Threads. Listing 2-1 shows an example of UBB configuration for ATMI Java Server. Listing 2-1 UBB Configuration for ATMI Java Server *SERVERS TMJAVASVR SRVGRP=TJSVRGRP SRVID=3 CLOPT="-- -c /home/oracle/app/javaserver/TJSconfig.xml" MINDISPATCHTHREADS=2 MAXDISPATCHTHREADS=3 Programming an Oracle Tuxedo Application Using Java 2-1 Note: The minimum value of MAXDISPATCHTHREADS you specify in UBBCONFIG for the Java server should be 2.