oracle10g build j2ee applications student guide - volume 2.pdf

Oracle10g: Build J2EE Applications

Student Guide • Volume 2

D17247GC10Production 1.0May 2004D39457

®

Copyright © 2004 Oracle. All rights reserved.

This documentation contains proprietary information of Oracle Corporation. It is provided under a license agreement containing restrictions on use and disclosure and is also protected by copyright law. Reverse engineering of the software is prohibited. If this documentation is delivered to a U.S. Government Agency of the Department of Defense, then it is delivered with Restricted Rights and the following legend is applicable:

Restricted Rights Legend

Use, duplication or disclosure by the Government is subject to restrictions for commercial computer software and shall be deemed to be Restricted Rights software under Federal law, as set forth in subparagraph (c)(1)(ii) of DFARS 252.227-7013, Rights in Technical Data and Computer Software (October 1988).

This material or any portion of it may not be copied in any form or by any means without the express prior written permission of Oracle Corporation. Any other copying is a violation of copyright law and may result in civil and/or criminal penalties.

If this documentation is delivered to a U.S. Government Agency not within the Department of Defense, then it is delivered with “Restricted Rights,” as defined in FAR 52.227-14, Rights in Data-General, including Alternate III (June 1987).

The information in this document is subject to change without notice. If you find any problems in the documentation, please report them in writing to Education Products, Oracle Corporation, 500 Oracle Parkway, Redwood Shores, CA 94065. Oracle Corporation does not warrant that this document is error-free.

Oracle and all references to Oracle Products are trademarks or registered trademarks of Oracle Corporation.

All other products or company names are used for identification purposes only, and may be trademarks of their respective owners.

Authors

Lynn MunsingerSunitha Patel

Technical Contributors and Reviewers

Anna AtkinsonScott BrewtonKenneth CooperCraig HollisterTaj-ul IslamIstvan KissPeter LaseauGlenn MaslenMonica Motley-MosserNagavalli PataballaHolger Dindler-RasmussenGlenn StokolVasiliy StrelnikovVenkat Tallapragada

PublisherS. Domingue

Preface

1 IntroductionCourse Objectives 1-2Course Environment 1-4Course Overview 1-5About the Course Applications 1-8Order Entry Schema 1-9Human Resources (HR) Schema 1-10HR Application Flow Diagram 1-11Summary 1-12

2 J2EE OverviewObjectivesObjectives 2-2Java 2, Enterprise Edition Platform 2-3J2EE Platform 2-4Benefits of the J2EE Platform 2-5J2EE Components 2-7J2EE 1.3 Components 2-8J2EE Architecture 2-9Client-Tier Components 2-10J2EE Web-Tier Components 2-11What Is a Servlet? 2-13What Is a JavaServer Page (JSP)? 2-14Web-Tier Components: Summary 2-15Business-Tier Components 2-16Enterprise JavaBeans (EJB) 2-17J2EE Communication APIs 2-18J2EE Server 2-19Oracle Application Server 10g Containers for J2EE (OC4J) 2-21J2EE Applications 2-22Packaging J2EE Application Components 2-23JARs 2-24WARs 2-25EJB JARs 2-26EARs 2-27EAR File Structure for a J2EE Application: Example 2-28OC4J Architecture 2-29OC4J Server Configuration Files 2-30Relation of Configuration Files 2-31Data Sources 2-32Application Logging 2-33J2EE Application Deployment to Oracle Application Server 10g 2-34

Contents

iii

Oracle Enterprise Manager 2-35JDeveloper and J2EE 2-36Oracle JDeveloper 10g Environment 2-37Oracle JDeveloper 10g Visual Design Tools 2-38Summary 2-39Practice 2-1: Overview 2-40

3 Designing J2EE ApplicationsObjectives 3-2Realizing J2EE Benefits 3-3J2EE Issues 3-4J2EE Design Patterns 3-5Implementing Design Patterns by Using MVC 3-6The Model 3-7The View 3-8The Controller 3-9MVC in Oracle Application Server 10g Containers for J2EE 3-10Designing J2EE Applications 3-11Flow Diagram: Example 3-12Summary 3-13Practice 3-1: Overview 3-14

4 Creating the Web Tier: ServletsObjectives 4-2Overview 4-3About Java Servlets 4-4Principal Features of Servlets 4-5Life Cycle of Servlets 4-6HTTP Servlets 4-7Inside an HTTP Servlet 4-8Servlet: Example 4-9The doGet() Method 4-10The doPost() Method 4-11The HttpServletRequest Object 4-12The HttpServletResponse Object 4-13Methods for Invoking Servlets 4-14Your First Servlet 4-15Handling Input: The Form 4-16Handling Input: The Servlet 4-17Initialization and Destruction 4-18Error Handling 4-19Debugging a Servlet 4-20

iv

SingleThreadModel 4-21JDeveloper Environment 4-23Servlet Mapping 4-24Servlet Mapping in JDeveloper 4-25Invoking a Servlet 4-26Specifying J2EE Web Module Settings 4-27Creating a Connection to Oracle Application Server 10g 4-28Deploying to OC4J 4-29Summary 4-30Practices 4-1, 4-2, and 4-3: Overview 4-31

5 Accessing the Database with ServletsObjectives 5-2Review of JDBC 5-3Querying in JDBC 5-4JDBC and Servlets 5-5Synchronizing Shared Resources 5-6Transaction Handling 5-7Connection Pooling 5-9Data Sources 5-10Data Source Definition 5-11data-sources.xml: Example 5-12Using Data Sources 5-13Summary 5-14Practice 5-1: Overview 5-15

6 Using Advanced Techniques in ServletsObjectives 6-2Overview 6-3HTTP Headers 6-4Request Headers 6-5Sending a Response 6-6Response Headers 6-7Setting Status Codes 6-8Example 6-9Sending Multimedia Content 6-10Cookies 6-12Setting Cookies 6-13Retrieving Cookies 6-14About State Preservation 6-15State Preservation: Example 6-16

v

ServletContext 6-17RequestDispatcher 6-18RequestDispatcher: Example 6-19Servlet Filters 6-20Using Filters 6-21doFilter() Method 6-22Using Filters 6-23Configuring Filters 6-24Application Lifecycle Events 6-25ServletContext Events 6-26HttpSession Events 6-27Example of an Event Listener 6-28Error Handling 6-29Summary 6-30Practices 6-1 and 6-2: Overview 6-31

7 Maintaining State in J2EE ApplicationsObjectives 7-2Overview 7-3Session Basics 7-4Threading 7-6URL Rewriting 7-7HttpSession 7-8Session Objects 7-9Session-Based Page Counter 7-10Session Life Cycle 7-11Session Tracking in OC4J 7-12Sessions and Events 7-13Creating Distributable Applications 7-17Summary 7-18Practice 7-1: Overview 7-19

vi

8 Creating the Web Tier: JavaServer PageObjectives 8-2JavaServer Pages 8-3Comparing Servlets and JSPs 8-4Invoking JSPs 8-5The Date JSP 8-6The Date Servlet 8-7Automated JSP Features 8-8JSP Life Cycle 8-9Basic JSP Elements 8-10Declarations 8-11Expressions 8-12Scriptlets 8-13Implicit Objects 8-14Example 8-16Directives 8-18include: Example 8-19page Directive 8-20JSP and JavaBeans 8-22Using JavaBeans with JSP 8-23scope Attribute of <jsp:useBean> Tag 8-25Accessing and Setting Bean Property 8-26JSP XML Document 8-28Traditional Syntax Versus XML Syntax 8-29JDeveloper and JSPs 8-31Creating JSPs Visually 8-32JSP Tag Insight 8-33Summary 8-34Practices 8-1, 8-2, and 8-3: Overview 8-35

9 Modularizing JavaServer Pages Development with TagsObjectives 9-2Custom Tags 9-3Custom Tag Library Components 9-4Tag Handler: Example 9-5Tag Library Descriptors 9-6Using a Custom Tag 9-7Tags with Attributes 9-8Creating a Custom Tag in JDeveloper 9-9Tag Libraries in JDeveloper 9-10Registering Tag Libraries 9-11Using Tag Insight 9-14

vii

JSP Standard Tag Library (JSTL) 9-15Core Tag Library 9-16Utilizing Core Tags 9-18Expression Language 9-19Using Iteration Tags 9-20Using the URL Tags 9-21XML Tag Library 9-23SQL Tag Library 9-24Accessing a Database with SQL Tags 9-25Querying Using SQL Tags 9-26Inserting, Updating, and Deleting Data 9-27Formatting Tags 9-28Internationalization Concepts 9-29Internationalizing Strings 9-30Formatting Numbers and Dates 9-31Transforming XML Documents 9-34JSTL in JDeveloper 9-35Summary 9-36Practice 9-1: Overview 9-37

10 Communicating in J2EEObjectives 10-2Overview of RMI 10-3Role of RMI in J2EE 10-4Communication in a J2EE Environment 10-5How Clients Locate a Distributed Component 10-7Java Naming and Directory Interface (JNDI) 10-8J2EE Container and JNDI Interface 10-9Naming Service 10-10JNDI Terminology 10-11Main JNDI Class and Interface 10-12Accessing an Object in JNDI Namespace 10-13Getting the JNDI InitialContext 10-14Initial Context Factories 10-16lookup() Method 10-17Obtaining a Reference to a Local Resource 10-18Obtaining a Reference to a Remote Resource 10-19Setting JNDI Environment Properties 10-20Using RMI over HTTP Tunneling 10-24Using Environment References with JNDI 10-25Configuring Environment Variables 10-26Specifying an EJB Reference 10-28

viii

Configuring EJB References 10-29Configuring Data Source References 10-31Summary 10-33Practice 10-1: Overview 10-34

11 Creating the Business Tier: Enterprise JavaBeansObjectives 11-2Enterprise JavaBeans (EJB) 11-3When to Use EJBs 11-4Types of EJBs 11-5Session Beans 11-7Entity Beans 11-9Message-Driven Beans 11-10EJB Architecture 11-11EJB Server 11-12EJB Container 11-13Services Provided by the EJB Container 11-14EJB Client 11-16EJB Interfaces and Classes 11-17Remote Interface and Remote Object 11-18Home Interface and Home Object 11-19Local Interface and Local Home Interface 11-20EJB Bean Class 11-21The EJB Deployment Process 11-22ejb-jar.xml File 11-23orion-ejb-jar.xml File 11-24Creating an EJB in JDeveloper 11-25Using the EJB Wizard 11-26Using the EJB Wizard 11-27Adding Methods to the Bean 11-28Deploying to Oracle Application Server 10g from JDeveloper 11-29Summary 11-30Practice 11-1: Overview 11-31

ix

12 Implementing Business Tasks with Session EJBsObjectives 12-2Session Beans 12-3javax.ejb.SessionBean Interface 12-5Types of Session Beans 12-7When to Use Session Beans 12-9Life Cycle of a Stateless Session Bean 12-11Home Interface for Stateless Session Beans 12-12Remote Interface for Stateless Session Beans 12-14The Session Bean Class 12-15The Session Bean Class: Business Methods 12-17Bean Class for the Stateless Session Bean 12-18Deployment Descriptor 12-19Client Application 12-20Client Application for Stateless Session Beans 12-21Life Cycle of a Stateful Session Bean 12-25Home Interface for Stateful Session Bean 12-26Client Application for Stateful Session Bean 12-27Summary 12-28Practices 12-1 and 12-2: Overview 12-29

13 Managing Persistent Data in the Business TierObjectives 13-2Entity Beans 13-3Representing Data in Entity Beans 13-5When to Use Entity Beans 13-6Callback Methods to Load and Store Data 13-7Session Beans Versus Entity Beans 13-9Types of Entity Beans 13-11BMP Beans Versus CMP Beans 13-12Components of an Entity Bean 13-14Creating, Removing, Finding, and Selecting Entity Beans 13-15Home Interface of an Entity Bean 13-17Creating a Bean Instance 13-18Finding an Entity Bean Instance 13-20Removing an Entity Bean 13-22Home Methods of Entity Beans 13-23Component Interfaces of an Entity Bean 13-24Primary Key Class of an Entity Bean 13-25Bean Class of an Entity Bean 13-26javax.ejb.EntityBean Interface 13-28Life Cycle of an Entity Bean 13-30

x

Deployment Descriptor 13-32Summary 13-35Practice 13-1: Overview 13-36

14 Achieving State Management in the Business TierObjectives 14-2Features of BMP Entity Beans 14-3Developing a BMP Entity Bean 14-4Features of CMP Entity Beans 14-5Implementing Methods in CMP Beans and BMP Beans 14-7Developing a CMP Entity Bean 14-9CMP Bean: Example 14-10Bean Class of a CMP EJB: CMP Fields 14-11Remote Interface: Departments 14-12Home Interface: DepartmentsHome 14-13Bean Class: DepartmentsBean 14-14Deployment Descriptor ejb-jar.xml 14-17Mapping CMP Fields to Database Table Columns 14-21Default Mapping of CMP Fields to Database Table Columns 14-22Explicit Mapping of CMP Fields to Database Table Columns 14-23Client for Departments Bean 14-25Summary 14-28Practice 14-1: Overview 14-29

15 Container-Managed Relationships (CMRs)Objectives 15-2Relationships 15-3Implementing Relationships 15-4Cardinality and Direction of Relationships 15-5One-to-One Relationships 15-7One-to-Many Relationships 15-8Many-to-Many Relationships 15-9Oracle TopLink 15-10TopLink: Integration of J2EE Applications with Data Sources at Run Time 15-11TopLink: Integrated with Oracle JDeveloper 10g 15-12Implementing Relationships 15-13Defining Abstract Accessor Methods 15-14Accessor Methods in 1:1 Relationships 15-15Accessor Methods in 1:M Relationships 15-16Checking Relationship Mappings in JDeveloper 15-17Accessor Methods in M:N Relationships 15-18

xi

Implementing a Relationship in the Deployment Descriptor 15-19Implementing 1:1 Relationships 15-21Implementing 1:M Relationships 15-23Implementing M:N Relationships 15-25Mapping Relationship Fields to Database 15-27Default Mapping of Relationship Fields 15-28Explicit Mapping of Relationship Fields 15-30Using JDeveloper to Create CMR Beans 15-31Summary 15-32Practice 15: Overview

16 Developing Message-Driven BeansObjectives 16-2Overview of Messaging Systems 16-3Types of Message Consumption 16-4Java Message Service (JMS) 16-6JMS Application Architecture 16-7Point-to-Point Model 16-8Publish-and-Subscribe Model 16-9Using JMS Interfaces 16-10JMS Message Structure 16-12Sending a Message to a Queue 16-13Receiving Messages 16-15Asynchronous Message Delivery 16-16Message-Driven Beans 16-17MDB Architecture 16-18Associating JMS Resources with an MDB 16-19State Diagram of an MDB 16-20Developing MDBs 16-22Interfaces to Be Implemented for MDBs 16-23Implementing an MDB Class 16-24Receiving Messages in an MDB Class 16-25Creating the Deployment Descriptor 16-26ejb-jar.xml: Example 16-28Mapping in OC4J-Specific Deployment Descriptor 16-29orion-ejb-jar.xml: Example 16-30Creating an MDB with JDeveloper 16-31Testing the MDB 16-34Summary 16-35

xii

17 Integrating J2EE ComponentsObjectives 17-2Overview 17-3Creating Remote Clients for EJBs 17-4Importing the EJB Home Interface 17-5Create a Reference to the EJB 17-6Passing Arguments to the EJB Method 17-7Creating an EJB Reference 17-8Creating Local Clients for EJBs 17-9ejb-local-ref Element 17-10EJB Tags 17-11useHome Tag 17-12useBean Tag 17-13createBean Tag 17-14iterate Tag 17-15Using the EJB Tags 17-16Deploying an Application: Web Tier 17-17Deploying an Application: EJB Tier 17-18Deploying an Application: EAR File 17-19Deploying from Oracle Enterprise Manager 17-20Summary 17-21Practice 17-1 and 17-2: Overview 17-22

18 Distributing Modular Applications: Introduction to Web ServicesObjectives 18-2What Is a Web Service? 18-3Web Service 18-4Service-Oriented Architecture 18-6Web Services Constituents 18-7Benefits of Web Services 18-9Web Services Model 18-11RPC-Style Web Services 18-12Document-Style Web Services 18-13Oracle Support for Web Services 18-14SOAP: XML Messaging for Web Services 18-15Communication with SOAP 18-16SOAP Messages 18-17Web Services Description Language (WSDL) 18-19WSDL 18-20UDDI Registry 18-22How UDDI Is Used 18-24Searching for a Web Service by Using UDDI 18-25

xiii

UDDI Specification 18-26tModel 18-27UDDI Support in Oracle JDeveloper 10g 18-31UDDI Browsing with Oracle JDeveloper 10g 18-32UDDI Publishing and Browsing with Oracle Enterprise Manager 18-33Summary 18-34Practice 18-1: Overview

19 Distributing Modular Applications: Developing Web ServicesObjectives 19-2Oracle Application Server 10g Web Services 19-3Developing a Web Service with a Stateless Java Class 19-4Defining an Interface 19-5Defining a Stateless Java Class 19-7Creating the Web Service 19-10Creating the Client Application 19-11Deploying the Web Service 19-13Testing the Web Service 19-14Web Service Home Page 19-15Testing the Deployed Web Service with Home Page 19-16Testing the sayHello Operation 19-17Serializing and Encoding Parameters and Results 19-19Developing a Stored Procedure Web Service 19-20Generating Wrapper Classes Using JPublisher 19-21Exposing a Function as a Web Service by Using Oracle JDeveloper 10g 19-22Publishing the Package as a Web Service 19-23JMS Web Services 19-24Summary 19-26Practice 19-1: Overview

20 Implementing Security in J2EE ApplicationsObjectives 20-2Goals of J2EE Security Architecture 20-3Overview of J2EE Security Architecture 20-4Java Authentication and Authorization Service (JAAS) 20-5Authorization of a Client 20-8JAAS Provider Types in OC4J 20-9Configuring Security 20-10Defining the Users, Groups, and Roles 20-11Managing Users and Groups with the JAZN Admintool 20-13Defining the Logical Roles 20-15

xiv

Defining and Using Logical Roles in Web Applications (web.xml) 20-16Defining and Using Logical Roles in EJBs (ejb-jar.xml) 20-18Mapping Logical Roles to Users and Groups 20-19Programmatic Access to a Caller’s Security Context 20-20Client Authentication 20-21EJB Client Authentication with the jndi.properties file 20-22EJB Client Authentication with a Hashtable 20-23Setting Access Control with JDeveloper 20-24Creating Web Application Security Roles 20-25Web Application Login Authentication 20-26Web Application Authorization 20-27Creating EJB Security Roles 20-28Setting Method Permissions 20-29Method Access in EJB Deployment Descriptors 20-30Creating a Mapping for the Logical Roles 20-31Mapping JAZN Identities to a Logical Role 20-32Mapping Results in orion-ejb-jar.xml 20-34Accessing the EJB with New Permissions 20-35Summary 20-36Practice 20-1: Overview 20-37

21 Oracle Application Server 10g Transaction SupportObjectives 21-2What Is a Transaction? 21-3Enterprise JavaBeans (EJB) Support for Transactions 21-4EJB Transaction Model 21-5Demarcating Transactions 21-6Container-Managed Transactions 21-7CMT: Transaction Attributes 21-8Transaction Attribute: NotSupported 21-10Transaction Attribute: Required 21-11Transaction Attribute: Supports 21-12Transaction Attribute: RequiresNew 21-13Transaction Attribute: Mandatory 21-14Transaction Attribute: Never 21-15CMT: The setRollbackOnly() Method 21-16JDeveloper: Setting Transaction Attributes 21-17Java Transaction API (JTA) 21-19JTA: The UserTransaction Interface 21-20Bean-Managed Transactions Demarcation 21-21BMT Demarcation: Process 21-22Using UserTransaction Support in EJBs 21-23Client-Demarcated Transactions Using UserTransaction 21-24BMT Demarcation: Restrictions 21-25

xv

Local and Global Transactions 21-26Single-Phase Commit 21-27Data Source Revisited 21-28Default data-sources.xml 21-29Emulated Versus Nonemulated Data Sources 21-30Retrieve Connection to Data Source 21-31Global Transaction Resource Request Flow 21-33Resource Request Flow 21-34Enlisting Database Resources 21-36Summary 21-38

A Practice SolutionsB Schema DescriptionsC Oracle JDeveloper 10g Quick ReferenceD BMP Entity EJBs J2EE Connector Architecture

xvi

Copyright © 2004, Oracle. All rights reserved.

Managing Persistent Data in the Business Tier

Entity EJBs

Oracle10g: Build J2EE Applications 13-2

13-2 Copyright © 2004, Oracle. All rights reserved.

Objectives

After completing this lesson, you should be able to do the following:• Identify the features of an entity bean• Distinguish between session beans and entity

beans• Decide when to use an entity bean• Describe the various components of an entity

bean• Differentiate bean-managed persistent beans from

container-managed persistent beans

ObjectivesThis lesson introduces the concept of entity beans and the different types of entity beans. You learn about the different components of an entity bean and the differences between entity beans and session beans.



Entity Beans

• Are objects that can be stored in permanent storage

• Represent persistent data in the database• Can be uniquely identified• Do not contain complex business logic • Do not model business processes but manage

data for such processes• Can serve multiple clients simultaneously

Entity BeansEntity beans are objects that can be stored permanently. They represent data stored in the database in the form of objects. Each object can represent a row in a table, and each field of the table can be a variable of the object.Why Data Should Be in the Form of ObjectsData in the form of objects is easier to handle and manage. Related data can be grouped together. For example, all data related to a particular employee (employee ID, first name, last name, and so on) can be grouped together in an object. You can also provide methods to retrieve or manipulate the information that is associated with an object.To summarize, entity beans are objects just like session bean objects. However, they represent persistent data in the database. Entity beans are generally represented by nouns such as names, departments, bank accounts, addresses, phone numbers, and so on.


Entity Beans (continued)How to Identify a Particular Entity BeanYou have learned that an entity bean can represent a row in a table. Consider 10 entity bean objects that contain data corresponding to 10 employees. How can you find an entity bean that represents data for employee X? Entity beans are uniquely identified by primary keys. The primary key in our case can be the employee ID; it can be a combination of different fields. The primary key is an object that can contain any number of attributes. This object basically contains data that is needed to identify the entity bean.Entity beans do not model business processes, which means they do not contribute to workflow management. However, they manage data for business processes. Entity beans can perform data validation and transformation. For example, an entity bean can take employee details, validate them, and update the table. They do not contain complex business logic.Entity beans can serve multiple clients simultaneously. If personnel from two different departments want to check the details for employee X and update the details, they need not deal with the same instance. Many entity bean instances can represent the same underlying data. The synchronization of the bean with the underlying data storage is handled by the container. Therefore, multiple clients can use the same data while operating with separate instances.The instance of an entity bean need not always point to the same data in the database. Bean instances are pooled and dynamically assigned to handle different data instances. For example, one instance holding the data of employee X can serve a client. When this bean is passivated and placed in the pool, the container can pick up the same instance to represent the data of employee Y. However, the data must be of type employee.



Representing Data in Entity Beans

TableEntity bean object

int xString sfloat fint y

double d

Representing Data in Entity BeansEntity beans are long-lived and can survive system crashes because they represent persistent data stored in a database. Entity beans can survive even database crashes because the entity bean instances can be created and populated with the required data when the database is functioning.To store the state of any object, the object should be serialized and stored in permanent storage. Similarly, business data can be serialized and stored. However, obtaining individual data from the serialized business data is difficult and tedious. Instead of serializing each object, you can dismantle each object into its parts and store them separately in an object. The table in the slide contains five fields and the entity bean contains five variables that correspond to each of these fields. It is like creating a class with five variables that can hold data from the table. When these objects have to be loaded with the data from the database, you can instantiate an object of this class, read the data from the database, and populate the instance variables with the data read. Loading and storing the data is automatically done by containers and you do not have to provide any code. There are two callback methods that perform the data transfer: ejbLoad() and ejbStore(). The ejbLoad() method reads the data from the database into the entity bean’s in-memory fields. The entity bean objects can then be modified in memory to change the values of data. The ejbStore() method saves the bean instance fields to the database.



When to Use Entity Beans

You can use an entity bean in the following situations:• To represent a business entity • When the state of the bean must be persistent• When you need to represent a relationship

between entities

When to Use Entity BeansYou can use an entity bean in any of the following situations.

• When you need to represent a business entity with a bean: An entity bean represents real-world business entities such as employees, products, and so on. The sole purpose of an entity bean is to represent and manage the persistent data. Each entity bean can represent a row of data in a database. In an online shopping business scenario, you can use entity beans to represent products, prices, customers, or shopping carts, whereas you use session beans to represent business logic such as calculating the total price of the products in the shopping cart, and so on.

• When you must store bean state to a persistent storage: Entity beans store persistent state and can survive a server crash. That is, even if the server crashes, you do not lose the bean state, which is stored in the database or any other persistent storage. When you restart your application, you can load the bean state from the persistent storage.

• When you need to represent relationships between various entities: Because an entity bean may represent a relational database table, you can form relationships between various database tables, representing each of them as an entity bean. For example, a CUSTOMER bean may have a one-to-many relationship with an ORDER entity bean.



Callback Methods to Load and Store Data

• ejbLoad()loads the data from the persistent storage to the bean.

• ejbStore()saves the data from the bean instance to the persistent storage.

Callback Methods to Load and Store DataAll session beans implement javax.ejb.SessionBean, whereas entity beans implement the javax.ejb.EntityBean interface. The EntityBean interface also has callback methods that are used by the container for life-cycle management, as in the SessionBean interface. They are setEntityContext(), unSetEntityContext(), ejbActivate(), ejbPassivate(), and ejbRemove(). In addition to these callback methods, the EntityBean interface has two more methods—ejbLoad() and ejbStore()—that are used to transfer data between persistent storage and the bean instance. You now see who invokes these methods and when they are invoked.The Enterprise JavaBeans (EJB) container provides the run-time environment for EJB. It also provides necessary services such as transaction management, resource management, security, and so on. The container manages the life cycle of the EJB by instantiating the bean and by allocating and deallocating the resources as the need arises. It is responsible for invoking the ejbLoad() and ejbStore() methods. The container automatically calculates when the data needs to be refreshed, depending on the transactions that happen with an entity bean.


Callback Methods to Load and Store Data (continued)Therefore, you need not synchronize the objects with the underlying database to reflect the latest data. The container can invoke these methods anytime but ensures that they are not invoked when a business method is being executed. You do not need to decide when to retrieve (ejbLoad()), persist (ejbStore()), create (ejbCreate()), or delete (ejbRemove()) persistent entries.Entity beans are objects that are placed in permanent storage. When an entity bean instance is passivated, the state of that instance must be stored, which means the fields of the instance must be loaded into persistent storage. To achieve this, the container invokes the ejbStore() method immediately before passivating the bean.When an entity bean instance is activated, its fields must have the recent data from the database. To load data into the bean instance, the container invokes the ejbLoad()method after activating the bean.



Session Beans Versus Entity Beans

Session Beans:• Are represented by

verbs because they model workflow

• Are short-lived and have a lifetime of a client session

• Manage their state, but do not contain callback methods to manage data because they do not represent data in the persistent storage

Entity Beans:• Are represented by

nouns because they model business data

• Are long-lived and do not depend on a client’s session

• Contain callback methods for managing data (create, retrieve, persist, and so on) in the persistent storage

Comparing Session Beans with Entity BeansSession beans model a workflow. In an online shopping scenario, the session beans can be responsible for displaying a catalog to the client, calculating the total price of the products in the shopping cart, and so on. The session beans contain complex business logic to successfully manage the workflow. Entity beans model business data. They can be responsible for persistent storage of the products in the shopping cart of a client, storage of product information and customer information, and so on. They do not contain complex business logic.Session beans are represented by verbs, and their actions are initiated by the client and end when the client closes the session. They are short-lived. Entity beans are independent of a client’s session and because they represent persistent data, they can last for years.Both stateful sessions and entity beans manage their states and, therefore, can undergo passivation and activation. However, entity beans have separate callback methods for saving state during passivation and for loading state during activation. Stateful session beans can implement the Synchronization interface, so they can be notified of any “database”commit or abort operations. For stateful session beans, passivation means that the instance is “flattened” and possibly the instance is swapped out of the main memory. Activation means the bean is swapped into the main memory.


Comparing Session Beans with Entity Beans (continued)For entity beans, passivation means that the bean loses its identity. Activation means that the bean gains its identity.Session beans are destroyed in the event of server, machine, or network crashes. However, for OC4J clustering, the stateful session beans survive crashes. Entity beans are objects that can be stored permanently. Therefore, crashes do not affect the life cycle of an entity bean. In the event of a crash, the entity bean instances can be re-created and initialized with the previous state of the bean instance.



Types of Entity Beans

• Container-managed persistent (CMP) beans: The container provides the logic to search and manipulate the persistent data.

• Bean-managed persistent (BMP) beans: The bean provider codes the logic to search and manipulate the persistent data in the callback methods.

Types of Entity BeansBased on the mechanism of managing persistent data, the entity beans are classified as:

• Bean-managed persistent beans: In bean-managed persistent (BMP) beans, the bean developer must code the logic for persisting data. The bean class should include a set of JDBC calls and database queries to retrieve, insert, and delete data from the database. Therefore, in BMP beans, the bean contains the code to manage the persistent data. The developer should know what database is used and the mapping of the beans’ fields to the database. BMP beans can store data in a Lightweight Directory Access Protocol (LDAP) directory.

• Container-managed persistent beans: Unlike BMP beans, in container-managed persistent (CMP) beans, the container manages the persistent data. You need not hard-code persistence in the bean. The necessary information about managing the persistence is provided to the container in the bean’s deployment descriptor. The deployment descriptor specifies the public fields of the bean that are mapped to the database tables and columns. These fields are called container-managed persistent fields (CMP fields). After these CMP fields are defined, the container generates theJava Database Connectivity (JDBC) logic that is needed to search or save the state of the bean instance into the database.

In EJB 2.0, CMP beans use abstract persistence schema to represent and manage complex relationships between entity beans.



BMP Beans Versus CMP Beans

• BMP beans:– Contain code for managing data persistence– Provide flexibility for bean developers to manage

state– Are complicated to program

• CMP beans:– Do not contain code for managing persistence

because the container manages the persistence– Use abstract persistence schema and define the

data retrieval/manipulation logic in the deployment descriptor

– Are easier to program and contain lesser code

BMP Beans Versus CMP BeansPersistence Management

• For bean-managed persistence, the bean developer should provide the logic to store and reload the data into and from the database. For example, this can be done through the SQL INSERT/UPDATE statements in ejbCreate()and ejbStore(), respectively, and SQL SELECT statements in the ejbLoad()callback method.

• For container-managed persistence, the container invokes abstract persistence schema that defines storing and reloading data into and from the database. The container always invokes the ejbStore()method immediately before commit, and invokes the ejbLoad()method immediately after instantiating CMP data from the database. The bean developer can provide additional logic such as preparing the data before committing or manipulating the data after it is refreshed from the database. The data retrieval/manipulation logic is specified in the deployment descriptor by using EJB query language (EJB QL).


BMP Beans Versus CMP Beans (continued)Advantages and Disadvantages of Using a CMP BeanThe advantage of container-managed persistence is that the bean can be defined independently of the database that is used to store its state. Because the bean state is defined independently, it provides more reusability and flexibility across applications.The disadvantage of container-managed persistence is that sophisticated mapping tools are required to define the mapping of a bean’s fields to the database. The mapping could be as simple as a direct mapping of one bean field to a column in one table. In some cases, it could be as complicated as mapping a bean’s field to a complex relational database join. Advantages and Disadvantages of Using a BMP BeanThe advantage of a bean-managed persistence is that it gives you more flexibility in managing the state between the bean instance and the database. When it is complicated to map bean instance fields to the database using a CMP bean (as when defining complex joins), bean-managed persistence is an alternative. The disadvantage of bean-managed persistence is that it is more complicated to define thebean persistence, because this is dependent on the type of database and data manipulation on that database. Any changes in the database structure must be reflected in the bean instance’s definition. The persistence mechanism must be defined in the callback methods. You must also define the methods that are defined in the bean’s home interface.



Components of an Entity Bean

• Home interface: Is used by clients to create, find, and destroy EJB objects

• Component interface: Contains the declaration of all business methods in the bean class that can be invoked by the client

• Bean class: Represents persistent data and contains methods to access or manipulate that data

• Primary key class: Is used to uniquely identify an entity bean instance

• Deployment descriptor: Contains information that is used by the container

Components of an Entity BeanA client uses the home interface reference to create, find, or destroy entity objects. The functionality of home interfaces for entity beans is the same as that for session beans.A client uses the component interface reference to access business methods from a bean instance. This interface is mainly used to expose business methods to the client.The bean class implements the methods that are declared in home and component interfaces. The bean class mainly contains business logic to access or manipulate business data. For BMP beans, the bean class also implements the persistence mechanism.The primary key class is the unique identifier for the entity bean. The container provides the run-time environment for the beans and manages its life cycle. The information that is needed by the container is picked up from the deployment descriptors on deployment.



Creating, Removing, Finding, and Selecting Entity Beans

• ejbCreate(): Initializes the entity bean in memory. This method may also insert the corresponding data into the persistent storage.

• ejbRemove(): Removes the database data but does not remove the in-memory entity bean instance. The instance may return to the pool and release all resources in the ejbPassivate()method.

• Finder methods: Used to find an entity bean.• Selector methods: Used to select entity beans and

values of CMP fields.

Creating, Removing, Finding, and Selecting Entity BeansEntity beans directly represent the persistent data in the database. Entity beans are synchronized by the container to reflect the latest data in the database. Entity beans are initialized by the ejbCreate() method. This method is invoked by the container. Initializing the entity bean means initializing the database data or inserting data into the persistent storage. In a bean-managed persistent bean, the ejbCreate() method should contain code to create the database data. In a container-managed persistent bean, the container manages the database data and, therefore, the ejbCreate() method does not have any implementation.To destroy the entity bean’s data in the database, the container calls the ejbRemove()method. This method does not remove the in-memory entity bean instance, but removes the database data. Therefore, the entity bean instance can be used to represent some other data.The finder methods are used to find an existing entity bean. You can have many different finder methods for an entity bean. This enables you to search an entity bean or multiple beans with different attributes. The logic for finding data can be specified in the deployment descriptor by using EJB QL. In addition to finder methods, a CMP bean can have ejbSelect() methods, which are implemented through EJB QL in the deployment descriptor.


Creating, Removing, Finding, and Selecting Entity Beans (continued)The ejbSelect() methods are similar to ejbFind() methods. They also use EJB QL to retrieve information. However, unlike ejbFind() methods, these methods are not exposed to a client and they are used only in the EJB’s implementation. ejbFind()methods return entities, whereas ejbSelect() methods can return entities and the values of CMP fields.Though ejbSelect() methods are not exposed to clients, they provide component developers with access to the powerful facilities of the query language to access entities and their container-managed fields.



Home Interface of an Entity Bean

• Remote home interface:– Extends the javax.ejb.EJBHome interface– Can be accessed by remote clients by using Java

Naming and Directory Interface (JNDI)– Allows client to create handles for later reference

• Local home interface:– Extends the javax.ejb.EJBLocalHome interface– Can be accessed by local clients

• Remote/local home interface:– Contains methods to create, find, or remove entity

objects– Contains business methods that are not applicable

to a specific instance (home methods)

Home Interface of an Entity BeanHome interface contains methods that enable the client to create, find, or remove entity objects. Home interface also supports business methods called home methods that are not specific to any bean instance. You can use finder methods to select the bean based on any of its attributes. A client can save the handle of a home interface reference, which is used to access the home interface at a later time.A client locates the home interface of an entity bean by first finding the JNDI initial context.

Context initCtx = new InitialContext();

Then, a reference to the home interface is obtained by looking up the home interface at that context.

ProdHome pHome = (ProdHome) javax.rmi.PortableRemoteObject.narrow

(initCtx.lookup("java:comp/env/ejb/product"), ProdHome.class);

If it is a local home interface, then the syntax is:ProdLocalHome pHome = (ProdLocalHome)initCtx.lookup("java:comp/env/ejb/product");



Creating a Bean Instance

• An entity bean can have one or more create()methods, or none defined in its home interface.

• The create() method:– Enables a client to create a row in the database

table that corresponds to the entity bean– Contains parameters that initialize the state of the

created entity object– Returns the remote/local interface reference of the

entity beans– Throws CreateException and any user-defined

exceptions– Throws RemoteException if it is part of a remote

home interface

Creating a Bean Instance An entity bean can have one or more create() methods, or none defined in its home interface. A create() method is invoked by the client application to create a bean instance. If there is no create() method available, then the client cannot request a bean instance. However, an entity bean instance can be created by creating a record in the underlying database. In this case, the bean can only be accessed through the findxxx()methods. The general naming standard of methods to create bean instances is create(...).The parameters of a create() method are used to initialize the state of the entity bean. The create() method of a home interface should throw the javax.ejb.CreateException exception. The create() method of a remote home interface should additionally throw the java.rmi.RemoteException exception.A create() method must return the component interface reference of the entity bean.


Creating a Bean Instance (continued)An example of a create() method in a home interface is as follows:

public interface ProductHome extends javax.ejb.EJBHome{public Product create() throws javax.ejb.CreateException,java.rmi.RemoteException;public Product create(Integer prodId, Stringdescription) throws javax.ejb.CreateException,java.rmi.RemoteException; ...

}

A client can then create a new bean instance as follows:Product prod = productHome.create(123, "Keyboard");



Finding an Entity Bean Instance

An entity bean:• Can have one or more finder methods in home

interface• Must have a findByPrimaryKey(primarykey)

method• Has finder methods that:

– Find row or rows in the database table – Contain parameters that locate the requested entity

object– Return entity bean’s component interface reference

or collection of objects of component interface type– Must throw FinderException– Must throw RemoteException in a remote home

interface– Have find as a prefix in their names

Finding an Entity Bean Instance An entity bean can have one or more finder methods defined in its home interface. Because each entity bean represents a record from the database, there must be a primary key to uniquely identify each bean instance. To be able to uniquely identify each entity bean instance, the home interface must contain a mandatory findByPrimaryKey(primarykey) method. This method can accept only one argument, of the primary key type. In addition to this method, the home interface can also define a few other finder methods. The return type of each finder method is either the bean’s component interface or Collection of objects of the component interface type.The naming standard of methods to find bean instances is findxxx(...). For each finder method in the home interface, there should be a corresponding ejbFindxxx() method in the bean class.Finder methods should throw the javax.ejb.FinderException exception. Finder methods of a remote home interface should additionally throw thejava.rmi.RemoteException exception.


Finding an Entity Bean Instance (continued)An example of a find method in a home interface is as follows:

public interface ProductHome extends javax.ejb.EJBHome {

public Product findByPrimaryKey(Integer proId) throws javax.ejb.FinderException,

java.rmi.RemoteException;public Product findByDescription(String description)

throws javax.ejb.FinderException,java.rmi.RemoteException;...

}

Note that the finder methods return a component interface reference, which is nothing but the EJB object. A client can then find a bean instance as follows:

Product prod = productHome.findByDescription("Keyboard");



Removing an Entity Bean

• An entity bean with remote home interface:– Can have one or more remove() methods:

remove(Handle handle) and remove(Object primarykey)

– Throws RemoteException and RemoveExceptionfrom remove() methods

• An entity bean with local home interface:– Can have one remove() method: remove(Object

primarykey)– Throws RemoveException from the remove()

method• remove() methods remove the entity object and

the row from the underlying database.

Removing an Entity BeanAn entity bean contains a remove()method, which when invoked by a client, removes the entity object and the underlying record in the database. The container may decide not to remove the instance, because it can be used to hold another row of the table. An entity bean with a remote home interface may contain one or more remove() methods. The remove(Handle handle) method removes the entity object that is identified by the handle. The handle identifies the entity object on a network. A client can obtain the handle of the entity object by invoking the getHandle() method on the component interface reference. The handle extends the java.io.Serializable interface. A client serializes the handle and the object to reobtain the reference to the entity object identified by the handle.The remove(Object primarykey) method removes the entity object that is identified by the primary key. The remove() methods should throw the RemoteException and RemoveException exceptions. An entity bean with local home interface contains only the remove(Object primarykey) method which throws RemoveException. Because there is no handle for local objects, there is only one remove() method for the entity bean with a local home interface.Accessing an entity object after it is removed throws the NosuchEntityExceptionexception.



Home Methods of Entity Beans

• Home methods are provided by a bean provider.• Home methods contain business logic that is not

specific to any bean instance.• An entity bean can have one or more home

methods, or none.• The arguments and return types of remote home

methods should be of RMI-IIOP type.

Home Methods of Entity BeansWhat Are Home Methods?Home methods are methods in the home interface of an entity bean. The home interface can contain business methods that are not specific to one instance of an entity object. Such methods in the home interface are called home methods. The business methods in the home interface should be generally applicable to any instance of the entity bean. The home methods of a home interface should throw RemoteException, and their return type should be of a legal RMI-IIOP type.When to Use Home Methods?If you want to code a method that applies equal discounts to all the products in the company, then you can implement the logic as a home method, because it is not specific to any particular product. Similarly, if you want to learn the total amount that is being paid as salary to the employees in an organization, then you can implement the logic as a home method, because it is not specific to any employee.



Component Interfaces of an Entity Bean

• Component interfaces define:– Business methods that are accessible by clients– Accessor methods for the bean attributes

• Remote interfaces:– Are referenced by remote clients – Extend the javax.ejb.EJBObject interface

• Local interfaces:– Are referenced by local clients– Extend the javax.ejb.EJBLocalObject interface

Component Interfaces of an Entity BeanA remote interface is the component interface of an entity bean. Clients access the entity object through the component interface reference. Component interfaces can be remote or local interfaces. Component interfaces define business methods that are accessible by the client. A component interface can also define accessor methods (get() or set()) to get or set bean attributes. The business and accessor methods are implemented in the bean class implementation. The component interfaces inherit methods that enable the client to obtain home interface reference and the primary key of the entity object. A remote interface that extends the javax.ejb.EJBObject interface is created similarly to a session bean. In addition to the methods specified above, a remote interface contains a method to obtain the handle of the entity object. Methods that are declared in the remote interface should throw the RemoteException exception.A local interface is the component interface that is accessed by local clients. A local interface extends the javax.ejb.EJBLocalObject interface. Methods in the local interface must not throw the RemoteException exception.



Primary Key Class of an Entity Bean

• Primary key:– Uniquely identifies each bean instance– Is used to find or remove an entity bean– Can be of any legal value type in RMI-IIOP

• The primary key class:– Should implement java.io.Serializable– Can have a single primary key (a single field) to

identify the entity bean– Can have composite keys (multiple fields) to

identify the entity bean

Primary Key Class of an Entity BeanA primary key uniquely identifies an entity bean according to the bean type, home interface, and container context from which it is used. The type of the primary key can be either a well-known type such as java.lang.String or primitive wrappers such as java.lang.Integer. In this case, you can define the type in the deployment descriptor. If the type is a complex type, then you create a serializable class. A primary key is applicable only to entity beans because entity beans represent records in the underlying database. Session beans do not represent any particular data in the database and, therefore, are not uniquely represented by primary keys.It is useful to create a primary key class when the primary key type is a complex data type. If the primary key class is a well-known data type, such as java.lang.String or Integer, then it can be directly supplied in the <prim-key-field> element of an XML deployment descriptor. The EJB specification requires that the fields in the primary key class be declared public. The primary key class is specified in the deployment descriptor of an entity bean.You learn about the primary key classes for BMP and CMP beans later in this course.



Bean Class of an Entity Bean

• Initializes the bean instance through the ejbCreate() and ejbPostCreate() methods

• Implements:– Finder methods through ejbFindxxx() methods– Home methods through ejbHomexxx() methods– Callback methods from the EntityBean interface– Business and private methods

Bean Class of an Entity BeanA bean class implementation is mainly created with the implementation of business logicmethods and callback methods. Container initializes the bean instance by using the ejbCreate() and ejbPostCreate() methods that are defined in the bean class. For each create(), find(), and findByPrimaryKey() methods declared in the home interface, implement the corresponding ejbCreate(), ejbFindxxx(), and ejbFindByPrimaryKey() methods in the bean class.A bean class implements business logic methods that are declared in the component interface. Any home() methods declared in the home interface are implemented in the bean class through the ejbHomexxx() methods. You can also add any private methods that are necessary in the bean class. In addition to the methods mentioned above, the bean class implements the life-cycle methods that are defined in the javax.ejb.EntityBeaninterface.Note: The method names corresponding to the create(), find(), and home()methods of the home interface have ejb as prefix and the word create/find/homefollowing the prefix, with an uppercase first letter.



Bean Class of an Entity Bean

• Contains ejbCreate() and ejbPostCreate()methods for each create() method.

• The ejbCreate() method:– Is invoked when a client invokes the create()

method to initialize persistent fields– Has primary key as return type

• The ejbPostCreate() method:– Is invoked after the entity bean is created and

before any other request from a client is processed– Has void as return type– Initializes any relationship fields for an entity bean

Bean Class of an Entity Bean (continued)For each create() method in the home interface, there should be matchingejbCreate() and ejbPostCreate() methods in the bean class. When a client invokes the create() method on the home interface, the container invokes theejbCreate() method. A row is inserted into the database with the values that are supplied in this method.The ejbPostCreate() method should match in signature to its corresponding ejbCreate() method. This method is invoked after the bean is created but before any client requests are serviced. This method is useful for initializing any relationship fields for the bean. Relationship fields can occur only after the ejbCreate() method is invoked and a bean is inserted into the database. The return type of the ejbPostCreate()method is void.



javax.ejb.EntityBean Interface

All entity bean classes should implement the javax.ejb.EntityBean interface.public interface javax.ejb.EntityBean implements javax.ejb.EnterpriseBean {public void ejbActivate();public void ejbLoad();public void ejbPassivate();public void ejbRemove();public void ejbStore();public void setEntityContext(EntityContext ctx);public void unSetEntityContext();}

javax.ejb.EntityBean InterfaceThe slide shows the definition of the EntityBean interface. This interface contains callback methods that are used during the life cycle of an entity bean. After the entity bean is created through the ejbCreate() method, the data is inserted into the database and is ready to be accessed by the client. When a client requests information, the data must be retrieved from the database and stored into the database when there is data manipulation such as update or delete of the entity bean. The container manages these activities by using the callback methods that are described in the slide.You have already learned that the ejbLoad()and ejbStore() methods are used to transfer data between persistent storage and the bean instance. These are the callback methods that are used for saving state during passivation and for loading state during activation. The ejbActivate() and ejbPassivate() methods are called by the container before and after an entity bean is swapped out and into the temporary storage.The container invokes the ejbRemove() method when the client invokes the remove()method. For a BMP bean, you must remove the data from the database that is associated with the bean within this method. For a CMP bean, this method is automatically implemented by the container.


javax.ejb.EntityBean Interface (continued)The RemoveException exception is thrown as an attempt to remove an EJB object when the enterprise bean or the container does not allow the EJB object to be removed.Any information about the bean that must be accessed during the lifetime of the bean can be initialized in the setEntityContext() method. This method is invoked only once by the container when the bean is initialized.Any resources that need to be released when the bean instance is destroyed, can be released in the unsetEntityContext() method.



Life Cycle of an Entity BeanDoes not

existnewInstance()

setEntityContext()

Pooled

unsetEntityContext()

ReadyejbLoad() ejbStore()

ejbCreate()ejbPostCreate() ejbActivate() ejbRemove()ejbPassivate()

Clients invoke business methods

Life Cycle of an Entity Bean• The container calls the newInstance() method to create a new instance of the

bean. The container invokes the setEntityContext() callback method to associate the entity bean with a context. The container creates instances when it wants to increase the number of instances in the pool, and not necessarily when the client calls the create() method. The bean instance is placed in the pool and is not associated with any particular entity object.

• The client invokes the create() method to create new data. The container then uses the instance in the pool to represent the new data. It invokes the ejbCreate()and ejbPostCreate() methods and initializes the entity bean. If the pool contains apassivated bean, then the container can use the same bean by invoking the ejbActivate() method before populating the bean with the data. This is indicated by dotted lines in the graphics because this method is executed only if there are already some beans that are passivated.

• Now, the bean instance is in the ready state. The container can invoke the ejbLoad() and ejbStore() methods to synchronize the entity bean data with the underlying data source. Clients can invoke the business methods on this bean.


Life Cycle of an Entity Bean (continued)• If the container decides to passivate the bean instance, it invokes the ejbStore()

method to load the data from the in-memory instance to the persistent storage. The container invokes the ejbPassivate() method when the container wants to dissociate the instance from the entity object without removing the entity object. When the instance is in the pool, it is no longer associated with an entity object identity. The container releases all the resources that are used by the bean, and the bean instance is then placed in the pool.

• If the client invokes the remove() method on the home object, then the container invokes the ejbRemove() method. The database data that is represented by the bean is deleted and the bean instance can be retained for reuse.

• If there are too many instances in the pool, or when there is no request for the instances, then the container dissociates the context associated with the bean by invoking the unsetEntityContext() callback method.



Deployment Descriptor<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE …><ejb-jar><enterprise-beans><entity><ejb-name>...</ejb-name><home>...</home><remote>...</remote><ejb-class>...</ejb-class><persistence-type>...</persistence-type><prim-key-class>...</prim-key-class><reentrant>False</reentrant><abstract-schema-name>...</abstract-schema-name><cmp-field> <field-name>...</field-name> </cmp-field><primkey-field>...</primkey-field></entity>

</enterprise-beans>...

Deployment DescriptorThe two main elements in the deployment descriptor of an entity bean are <enterprise-beans> and <assembly-descriptor>.The <enterprise-beans> element contains the details of the bean class, primary key class, and interfaces. This element contains a subelement called <entity>, which indicates that the enterprise bean being described is an entity bean. The <assembly-descriptor> element contains information about the security roles, methods that are accessible for different roles on different beans, and so on. It is the bean assembler’s responsibility to define these roles and responsibilities.The slide shows the elements in a deployment descriptor. <ejb-jar> is the root element of the descriptor. Note the various tags in <entity>. The <home>, <remote>, and <ejb-class> tags provide information about the elements of the entity bean. The <persistence-type> tag is used to specify whether the bean is a BMP bean or a CMP bean. <prim-key-class> contains the name of the primary class, which is used to uniquely identify the entity bean.


Deployment Descriptor (continued)ReentranceYou learned that when a client application invokes a method on an enterprise bean, the method is accessed through the remote interface of the bean. The client is not allowed to access the bean directly. This process is the same even if the client application is another enterprise bean. Also, you learned that multiple threads are not allowed into a bean. That is, even though entity bean instances are sharable (accessed concurrently), a client can access a bean only after another client who is using a method of that bean has finished. The bean instances are always single-threaded.Consider a client invoking a method on bean A, which further invokes a method on bean B. Here, bean A is a client of bean B. If bean B now tries to invoke a method on bean A, this situation is called a loopback. This is considered a reentrance and is not allowed in EJB. Session beans can never be reentrant. If a loopback is attempted, the RemoteException exception is thrown. Entity beans can be set to reentrant during deployment time. Reentrance is okay for entity beans if it is specified in the <reentrant> tag. Different transactions have their own entitybeans on which to operate. If multiple threads have the same transaction context (very unlikely) and access the same bean, then the calls are serialized.Note: A bean instance invoking its own methods is not considered as reentrance.The <reentrant> tag contains a Boolean value, which is used to indicate whether the entity bean is reentrant or not. The default value is False.For a CMP bean, the <abstract-schema-name> tag specifies the schema name to which the entity bean should be mapped. The <cmp-field> tags specify the field names whose persistence should be managed by the container.<primkey-field> indicates the CMP field that is the primary key field.



Deployment Descriptor

...<assembly-descriptor>

<security-role><description>Public</description><role-name>PUBLIC</role-name>

</security-role><method-permission>

<description>Public methods</description><role-name>PUBLIC</role-name><method>

<ejb-name>...</ejb-name><method-name>*</method-name>

</method></method-permission>

</assembly-descriptor></ejb-jar>

Deployment Descriptor (continued)The optional <assembly-descriptor> tag is used to define security attributes for the application.The <method-permission> tag in the above example indicates that all the methods of the EJB are accessible to a role named PUBLIC. The * in the method-name stands for all the methods of the bean.



Summary

In this lesson, you should have learned how to:• Identify features of an entity bean• Use entity beans• Distinguish between a session bean and an entity

bean• Develop components of an entity bean• Differentiate BMP beans from CMP beans• Describe the life cycle of an entity bean

SummaryIn this lesson, you should have learned about entity beans and different types of entity beans. You have seen the differences between session beans and entity beans, and should now be able to decide when to use entity beans. You should also have learned about the various components that build an entity bean and the life cycle of the entity bean.



Practice 13-1: Overview

This practice reviews entity bean concepts using paper-based questions.


Practice 13-11. Which two of the following statements regarding entity beans are true?

a. Live for the lifetime of a clientb. Are long-lived and, therefore, are independent of a client’s sessionc. Model a process or workflow and, therefore, are represented by verbsd. Contain complex business logic that is needed to process the workflowe. Represent persistent data. They model data but not business process and,

therefore, are represented by nouns.2. Which three of the following statements regarding finder methods are true?

a. An entity bean can have one or more finder methods. b. Finder methods find one row at a time in the database table.c. Finder methods find a row or rows in the database table.d. These methods must throw FinderException but need not throw

RemoteException.e. These methods must throw both FinderException and

RemoteException.f. They return home interface reference or collection of objects of home interface

type.3. For methods given in column A, choose appropriate statements from column B.

Loads the data from the persistent storage to the beanejbLoad()

Releases the resources held by the entity bean and saves the bean state to the underlying storage. The bean instance is put into a generic instance pool.

ejbStore()

Does not create new database data but loads some existing entity bean data. The developer must implement this method for BMP beans, and the container implements this for CMP beans.

ejbRemove()

Saves the data from the bean instance to the persistent storage

ejbPassivate()

Removes or deletes the database data, but the in-memory entity bean instance is retained by the container to handle different data/row of the table.

ejbFind()

BA


Practice 13-1 (continued)4. The ejbRemove()method of entity beans does not take any parameters. This method

is not called if the client times out. (True/False)5. Which two of the following statements regarding primary key classes are true?

a. Used to uniquely identify the entity bean instancesb. Contain only a single primary key to identify bean instancesc. Should implement java.io.Serializabled. Can be used to create an instance, but cannot be used to remove the instance


Achieving State Management in the Business Tier



Objectives

After completing this lesson, you should be able to do the following:• Describe the features of bean-managed persistent

(BMP) entity beans• Identify the features of a container-managed

persistent (CMP) entity bean• Describe the benefits of a CMP bean as compared

with a BMP bean• Develop and deploy a CMP bean• Develop a client for a CMP bean

ObjectivesYou have learned about different types of entity beans in the lesson titled “Managing Persistent Data in the Business Tier.” This lesson provides an overview of BMP beans and discusses CMP beans in detail. You learn to develop a CMP bean, deploy the bean, and invoke the methods on the bean with a client application.



Features of BMP Entity Beans

• The Bean provider provides the code for persistence management.

• BMP beans provide more flexibility in managing persistent data.

• The bean class of a BMP entity bean contains code for data access and manipulation.

• Callback methods contain code to map the entity bean instance to the data, load the data, and store the data in persistent storage.

• BMP beans are less portable.

Features of BMP Entity BeansIn bean-managed persistent beans, the bean provider provides the logic to access data and manipulate data in the persistent storage. This involves writing a lot of Java Database Connectivity (JDBC) code in the callback methods and business logic methods. For example, the ejbCreate() method contains a SQL INSERT statement to insert data into the database. When this method is executed, appropriate data is inserted into the database and this data is associated with an entity bean instance. When the data to be manipulated is more complex, involving complex joins between various tables from the underlying database, the BMP beans provide more flexibility to the bean provider for managing the interaction between the bean instance and the database. Bean-managed persistence is more complicated than container-managed persistence because the bean developer must explicitly write the persistence logic in the bean class, and this is dependent on the type of database and data manipulation on that database. Any changes in the database structure must be reflected in the bean instance’s definition. The persistence mechanism must be defined in the callback methods. Therefore, the BMP beans are less portable. For container-managed persistence, the details for the persistence, fields, and relationships to be managed are provided in the deployment descriptor.



Developing a BMP Entity Bean

To develop a BMP entity bean, you must create thefollowing: • A remote interface for the bean• A home interface• The primary key class• The bean class implementation• Support classes, such as exceptions• Necessary database tables• The J2EE deployment descriptor• A client application to access the EJB

Developing a BMP Entity BeanIn the lesson titled “Managing Persistent Data in the Business Tier,” the components of an entity bean and the differences between BMP entity beans and CMP entity beans were discussed. To develop a BMP entity bean, you must create the following components:

• A remote interface that contains declarations of business methods that are accessible to a client

• A home interface that contains the create(), find(), and home() methods to be implemented in the bean class

• A primary key class to uniquely identify each bean instance • A bean class implementation with all the persistent data management• Any support classes, such as exceptions• The database tables involved in the business logic of the entity bean• The deployment descriptor to identify the EJB, security roles, and the relationships

between various beans involved in the business process• A client application to access the EJB

You can also create an OC4J-specific deployment descriptor for mapping the resources that are used in the entity bean. This descriptor is optional, but provides portability.



Features of CMP Entity Beans

• Developers need not code the persistence logic in the bean because the containers provide it.

• CMP beans provide:– Portability across all EJB-compliant containers – A layer of data independence– Container-managed fields, which represent the

persistent fields in the database• Bean developers concentrate on the business

logic and provide empty implementations of the callback methods.

Features of CMP Entity BeansThe main goal of CMP beans is to provide portable EJBs across all compliant Enterprise JavaBeans (EJB) containers. You have already learned about BMP beans. In BMP beans, the bean provider must include JDBC code in the bean class to implement the persistence logic. The persistence logic may vary slightly depending on the persistence provider. Therefore, to be able to access the methods of the bean with a different persistence provider, the bean class may have to be redefined and recompiled. The CMP architecture mainly provides a layer of data independence between the entity bean instance and the persistence representation. In CMP beans, the bean class is an abstract class in which the bean provider provides only the business logic. The implementation of the logic (to manipulate the persistent data) is left to the container. CMP beans usually contain empty implementations of the callback methods. However, you can provide implementation for methods such as ejbActivate()if you want to acquire any bean-specific resources when the bean moves to the ready state. If you want a bean to serve a particular client whose state is available, then you can populate the bean with the client state information and then service the client. Similarly, you provide implementation for methods such as ejbPassivate()or unsetEntityContext() to release any such resources.


Features of CMP Entity Beans (continued)Container-Managed FieldsThe bean provider specifies the fields and relationships to be persisted through the deployment descriptor. The container collects the information and generates classes and interfaces that are necessary to persist the data and relationships during deployment and run time. This allows an entity bean to be redeployed on different containers and persistence providers without redefining or recompiling the class implementation. This also enables the bean developer to concentrate more on the business logic, leaving the implementation details to the container. The bean class contains fields called container-managed fields. These fields represent the fields in the table of a database that are represented by the entity bean. These fields are not explicitly defined in the bean class. However, the bean class contains abstract set() and get() methods for these fields. These methods should be public, because the container has to implement them and should have access to these methods.



Implementing Methods in CMP Beans and BMP Beans

ejbStore()

ejbLoad()

ejbcreate()

setXXX() andgetXXX()

ejbFind()

CMPBMPMethod

abstract

Implementing Methods in CMP Beans and BMP BeansFinder methods: CMP beans contain finder methods but the bean provider need not code the finder methods, such as findAll()and findByPrimaryKey(), in the bean class. The EJB container is responsible for finding data. In BMP beans, the bean provider can implement any number of ejbFind()methods and is responsible for finding data. Finder methods use SELECT statements to find appropriate data.ejbcreate(): In BMP beans, the create() methods are implemented to create new database data and initialize the bean instance. These methods use INSERT statements to create the data. In CMP beans, the create() methods do not create database data with INSERT statements. The container takes care of this. The ejbcreate()method in a CMP bean calls the set method to initialize the bean instance with the data.ejbLoad(): The ejbLoad() method of a BMP bean contains code to load the bean instance with the persistent data in the table. The ejbLoad() method uses a SELECTstatement to load the data. In CMP beans, the container is responsible for loading the data; therefore, this method has an empty implementation.


Implementing Methods in CMP Beans and BMP Beans (continued)ejbStore(): In a BMP bean, this method uses an UPDATE statement to store the data in the bean instance to the persistent storage. The container automatically extracts the container-managed fields and updates the data in the persistent storage. Therefore, this method has an empty implementation in CMP bean. set() and get() methods: The BMP bean contains the implementation for the set()and get() methods. In a CMP bean, these methods are abstract and are implemented by the container to set and get the container-managed fields.



Developing a CMP Entity Bean

To develop a CMP entity bean, you must:• Create a component interface• Create a home interface• Define a primary key for the bean• Create the bean class implementation• Create optional support classes such as

exceptions• Create the bean deployment descriptor• Ensure that the correct database table exists for

the bean

Developing a CMP Entity BeanThe following components must be developed for a CMP bean:

• A component interface that contains declarations of business methods that are accessible to a client. All CMP beans that participate in container-managed relationships must be in the same local scope. That is, the beans must reside in the same EJB container and use local interfaces rather than remote interfaces for obtaining related information. However, if the beans are not participating in such relationships, you can define a remote interface and access it from a remote client.

• A home interface that contains the create(), find(), and home() methods• A primary key class to uniquely identify each bean instance. The primary key field

must be declared in <prim-key-field> of the deployment descriptor. • An abstract bean class that is implemented by the container. The bean class provides

abstract methods for the CMP fields. • Any support classes such as user-defined exceptions and any dependent value classes.

Dependent value classes are serialized classes that an entity bean may use internally in its private methods, or expose to the client through public interface methods.

• The deployment descriptor to identify the EJB, the abstract persistence schema name, the CMP and container-managed relationship (CMR) fields, the type of relationship with other entity beans involved in the business process, the CMP bean version, the security roles, and so on. JDeveloper automatically creates the deployment descriptor for the bean.



CMP Bean: Example

• The example in this lesson creates a CMP entity bean to represent the DEPARTMENTS table with the following components:– Remote interface: Departments– Home interface: DepartmentsHome– Bean class: DepartmentsBean– Deployment descriptor: ejb-jar.xml

• Client for Departments bean: DepartmentsClient

CMP Bean: ExampleIn this lesson, you create a Departments entity bean that represents the DEPARTMENTSdatabase table. The slide shows the various components that must be developed for the Departments CMP entity bean. The DEPARTMENTS table is a relational table that contains the department_id (primary key), department_name, manager_id, and location_id (a foreign key that references the LOCATIONS table) columns. This example shows how to create the data in the persistent storage by using CMP beans. You will also see how to use the get() and set() methods of the CMP fields to access and modify the fields.The description of this table and other tables used in this course are detailed in Appendix B.



Bean Class of a CMP EJB: CMP Fields

• The bean class of a CMP EJB is an abstract class because it does not implement persistence logic.

• CMP fields in the deployment descriptor:– Correspond to columns of the persistent data table– Have names starting with a lowercase letter– Must be Java primitive types or Java serializable

objects• CMP field accessor methods in the bean instance:

– Must be abstract public methods; the container implements these methods

– Must have names in the following form: getFieldname()or setFieldname()

Bean Class for a CMP EJBThe bean instance of a CMP EJB is much different from that of a BMP EJB. The main difference between the two beans is in the implementation of the persistence logic. In a CMP bean, the container implements the persistence logic. The bean class is an abstract class that does not define the instance variables to hold container-managed persistent and container-managed relationship fields. The container generates the class that is necessary to implement the abstract classes defined in the abstract bean class.

• Container-managed persistence (CMP) fields:- Represent the columns in the underlying persistent database table related to the

CMP bean- Are defined in the deployment descriptor- Have names starting with a lowercase letter, and can be Java primitive or Java

serializable object types • Accessor methods for CMP fields:

- Are defined as get() or set() methods in the bean class implementation.- Must be public and abstract. They must follow the naming convention

getFieldname or setFieldname where fieldname is the CMP field name as defined in the deployment descriptor (starts with an uppercase initial letter).



Remote Interface: Departments

...import javax.ejb.EJBObject;import java.rmi.RemoteException;public interface Departments extends EJBObject {// set and get methods for CMP fieldsLong getDepartment_id() throws RemoteException;void setDepartment_id(Long newDepartment_id)throws RemoteException;

String getDepartment_name()throws RemoteException;

void setDepartment_name(StringnewDepartment_name) throws RemoteException;

...}

Remote Interface: DepartmentsThe code in the slide shows the remote interface of the Departments bean. The business methods defined for the CMP fields are exposed. These methods and one pair of get() and set() accessor methods for each of the CMP fields of the Departments bean are defined as abstract methods of the bean class DepartmentBean. No business method is declared to keep the example simple.



Home Interface: DepartmentsHome

import javax.ejb.EJBHome;import java.rmi.RemoteException;import javax.ejb.CreateException;import javax.ejb.FinderException;import java.util.Collection;public interface DepartmentsHome extends EJBHome {

Departments create() throws RemoteException,CreateException;

Departments findByPrimaryKey(Long primaryKey) throwsRemoteException, FinderException;

Collection findAll() throws RemoteException,FinderException;

Departments create(Long department_id, Stringdepartment_name) throws RemoteException,CreateException;

}

Home Interface: DepartmentsHomeThe code in the slide shows the home interface DepartmentsHome for the Departments bean.The example contains two create() methods: a no-argument method and a method that accepts all the CMP fields as parameters. The abstract bean class defines the equivalent ejbCreate()and ejbPostCreate()methods.The findByPrimaryKey() finder method accepts the primary key of type Long and returns a Departments object. The findAll() method lists all the departments, and the findByPrimaryKey()method lists the department with the specified department_id.



Bean Class: DepartmentsBean

...import javax.ejb.EntityBean;import javax.ejb.EntityContext;public abstract class DepartmentsBean implements EntityBean { private EntityContext context;

public void setEntityContext(EntityContextctx)

{ context = ctx;

}public void unsetEntityContext(){

context = null;}public abstract Long getDepartment_id();public abstract void setDepartment_id(LongnewDepartment_id);

...

Bean Class: DepartmentsBeanThe code in the slide shows the abstract bean class DepartmentsBean. This bean defines:

• An instance variable context to hold the entity context of the bean• setEntityContext and unsetEntityContext() methods to associate and

dissociate the entity bean and the context informationNote that there are no declarations for the CMP fields in the bean implementation. The information about the CMP fields and their mapping to the fields in the database is provided in the deployment descriptor.The get() or set() pair of accessor methods for each CMP field is declared. The accessor methods for only one field, department_id, are shown in this example. These methods have their names prefixed with get or set, followed by the name of the CMP field as defined in the deployment descriptor, with an uppercase initial letter.




...public Long ejbCreate(){ return null; }

public void ejbPostCreate(){ }

public Long ejbCreate(Long department_id,String department_name){setDepartment_id(department_id);setDepartment_name(department_name);return department_id;

}public void ejbPostCreate(Long department_id, String department_name){ }

...

Bean Class: DepartmentsBean (continued)The slide shows the code for the ejbCreate()and ejbPostCreate()methods that are equivalent to the create()methods defined in the home interface. The slide shows only two forms of the ejbCreate()method. You can have different overloaded forms of the ejbCreate() method. You set the values for the CMP fields by using the set()methods that are implemented for the CMP fields as shown earlier in this lesson.




...public void ejbActivate(){ }public void ejbLoad(){ }public void ejbPassivate(){ }public void ejbRemove(){ }public void ejbStore(){ }

}

Bean Class: DepartmentsBean (continued)The slide shows the callback methods that are implemented by the container.



Deployment Descriptor ejb-jar.xml

The main tags of the deployment descriptor for a CMP bean are:• <prim-key-class>: Type of primary key• <persistence-type>: Container• <cmp-version>: CMP 1.1 or 2.0 (default)• <abstract-schema-name>: For each entity bean• <cmp-field><field-name>: List of CMP field

names

Deployment Descriptor ejb-jar.xmlThe deployment descriptor plays an important role in a CMP EJB. In a BMP bean, the bean provider furnishes the statements to obtain and close the connection to data sources, perform the JDBC calls, define and manipulate the relationship among the beans, and so on. Because the container manages all the persistence in the CMP entity beans, the information necessary for the container to persist this data and the SQL statements must be defined in the deployment descriptor. The slide describes some of the important tags for a CMP bean. The mandatory <prim-key-class> tag indicates the type of the primary key for the table that the CMP entity bean represents. The primary key can be of system-defined data type such as String or Integer, or it can be a user-defined class type. If the primary key consists of a single field, then there must be a <primkey-field> tag that indicates which CMP field is used to represent the primary key.


Deployment Descriptor ejb-jar.xml (continued)The mandatory <persistence-type> tag describes whether the bean or the container provides persistence to the bean. For a CMP bean, the value is Container.The <cmp-version> tag indicates that the CMP bean implements CMP version 2.0 features. The EJB container vendors must support both the CMP 2.0 and 1.1 versions. If this optional tag is not defined, then the default value is 2.0.The optional <abstract-schema-name> tag is used to uniquely identify the abstract persistence schema name for each of the entity beans. An abstract persistence schema is a combination of the CMP and CMR fields that are defined in the deployment descriptor. The list of fields defined with the combination of <cmp-field><field-name> tags indicates the container-managed persistence fields in the bean class. In addition to themandatory <field-name> tag, there can also be an optional <description> tag to describe the CMP field. There must be one set of accessor methods in the abstract bean class corresponding to each of the CMP fields declared in the deployment descriptor.



Deployment Descriptor ejb-jar.xml...<ejb-jar><enterprise-beans><entity> <description>Entity Bean

( CMP )</description><display-name>Departments</display-name><ejb-name>Departments</ejb-name><home>mypackage1.DepartmentsHome</home><remote>mypackage1.Departments</remote><ejb-class>mypackage1.impl.DepartmentsBean</ejb-class><persistence-type>Container</persistence-type><prim-key-class>java.lang.Long</prim-key-class><reentrant>False</reentrant><cmp-version>2.x</cmp-version>

...

Deployment Descriptor ejb-jar.xml (continued)This slide shows the deployment descriptor for the Departments bean example.The logical name for the EJB is given as Departments in the <ejb-name> element. The home interface and the remote interface names are given along with the names of their packages in the <home> and <remote> tags. The bean class name is specified in the <ejb-class> tag.The value Container for the <persistence-type> element indicates that the entity bean is a CMP bean.The <prim-key-class> element shows that the example primary key class is of java.lang.Long type. This element is mandatory for an entity bean. If the primary key comprises a single field, then the CMP field that is used as primary key must be specified in the <primkey-field> element. This is shown in the following slide.The <reentrant> flag is set to False because the methods of the Departments bean do not call themselves. That is, loopbacks are not allowed in the methods of this CMP bean.The <cmp-version> tag indicates that CMP version 2.0 is used.



Deployment Descriptor ejb-jar.xml

<cmp-field><field-name>department_id</field-name>

</cmp-field><cmp-field><field-name>department_name</field-name>

</cmp-field><cmp-field><field-name>manager_id</field-name>

</cmp-field><cmp-field><field-name>location_id</field-name>

</cmp-field><primkey-field>department_id</primkey-field>

</entity></enterprise-beans>

</ejb-jar>

Deployment Descriptor ejb-jar.xml (continued)The container-managed persistence (CMP) fields are declared within the <cmp-field>element. There should be one CMP field declaration for each pair of get() or set()CMP field accessor methods that is defined in the bean class. This element contains an optional <description> element to describe the field and a mandatory <field-name> element to declare the field name. The name of this field should match the CMP field accessor method that is defined in the bean class. The name of the get() accessor method of a CMP field with a name field1 would be getField1().



Mapping CMP Fields to Database Table Columns

• Accept the defaults that are supplied by the container.

• Map explicitly to the columns in a database table by using the orion-ejb-jar.xml file:– Deploy the application by using only ejb-jar.xml– Modify the generated orion-ejb-jar.xml file with

the custom database, table, and column details– Use for more complex data representation of a bean

• JDeveloper provides easy mapping of the persistent fields to database tables.

Mapping CMP Fields to Database Table ColumnsAfter defining the CMP fields in the deployment descriptor, these fields must be mapped to database tables and columns. For these fields to be mapped to a database, you can take one of the following alternatives:

• Accept the defaults for these fields and avoid more deployment descriptor configuration. If you define the persistent fields in the ejb-jar.xml file, then OC4J provides the following mappings of these fields to the database.

• The persistent data mapping is configured within the orion-ejb-jar.xml file. If the data represented by your bean is more complex or you do not want to accept the defaults that OC4J provides for you, then you can map the persistent data to an existing database table and its columns within the orion-ejb-jar.xml file.

You can use JDeveloper to provide easy mapping of the persistent fields to the database tables and columns.



Default Mapping of CMP Fieldsto Database Table Columns

• Database: Default database as specified in the data-sources.xml file, which can be customized

• Table: Default table is created by a container with a unique name that combines the following:– EJB name defined in the deployment descriptor– JAR file name including .jar extension– Application name defined during deployment– An underscore and five-character hash code– Example: DeptBean_dept_jar_dept_xxxxx

• Column: With the same name as the CMP fields defined in the deployment descriptor; Java data types are translated to database data types in oracle.xml

Default Mapping of CMP Fields to Database Table ColumnsThe container provides mappings of the persistent fields that are defined in the ejb-jar.xml file to the database:

• Database: This is the default database that is specified in data-sources.xml. For the Java Naming and Directory Interface (JNDI) name, use the <location> element for nonemulated data sources and the <ejb-location> element for emulated data sources. Upon installation, the default database is a locally installed Oracle database that must be listening on port 1521 with a system identified (SID) of ORACLE. To customize the default database, change the first configured database to point to your database.

• Table: The container creates a default table with a unique table name. The table name is constructed with an EJB name, a JAR file name including the .jar extension (all dashes [-] and periods [.] are converted to underscores [_]) and an application name that you define during deployment. If the constructed name is greater than 30 characters, then the name is truncated at 24 characters. An underscore followed by five characters made up of an alphanumeric hash code is appended to the name for uniqueness. For example, if the EJB name is DeptBean, the JAR file is dept.jar, and the application name is dept, then the default table name is DeptBean_dept_jar_dept_xxxxx.

• Column names: Column names in the entity bean table have the same name as the<cmp-field> elements in the deployment descriptor.



Explicit Mapping of CMP Fieldsto Database Table Columns

<enterprise-beans><entity-deployment name="Departments" data-source="jdbc/hrDS" table="DEPARTMENTS"><primkey-mapping><cmp-field-mapping name="department_id“persistence-name="DEPARTMENT_ID" persistence-type="NUMBER(4)"/>

</primkey-mapping><cmp-field-mapping name="department_id“persistence-name="DEPARTMENT_ID" persistence-type="NUMBER(4)"/>

<cmp-field-mapping name="department_name“persistence-name="DEPARTMENT_NAME“persistence-type="VARCHAR2(30)"/>

...

Explicit Mapping of CMP Fields to Database Table ColumnsDeploy your application with only the ejb-jar.xml elements that are configured. Oracle Application Server 10g Containers for J2EE (OC4J) creates an orion-ejb-jar.xml file for you with the default mappings in them, which you can modify. When you create an entity bean, JDeveloper automatically creates this file. The mapping is done implicitly. The slide shows the orion-ejb-jar.xml file for the Departments bean. The <entity-deployment> element in the orion-ejb-jar.xml file contains information about the database table and the bean’s CMP fields.The example in the slide demonstrates how to map persistent data fields in your Departments bean instance to the database tables, and how to map the columns to the Oracle database table DEPARTMENTS.The <entity-deployment> name attribute identifies the bean. The data-sourceattribute defines the data source that is used by this bean. The table attribute defines the database table. The bean primary key, department_id, is mapped to the database table column department_id within the <primkey-mapping> element.The bean persistent data field department_name is mapped to the database table column department_name within the <cmp-field-mapping> element. Similarly, all the CMP fields are mapped to the corresponding columns in the table.


Mcomplex Data Types in CMP BeansWhile mapping CMP fields to database table columns, you need to take care of the data types that are being mapped. You can define simple data types and Java user classes that are serializable. If you have complex native data types, then you have to map them to the appropriate database type. For example, if you have java.util.Date or java.util.Time, then you should map it to Oracle database type DATE. The Date and Time map to DATE in the database because Date contains the time.You can map the database type CLOB to java.lang.String or a character array. You can also map VARCHAR2 for a string or character array; however, it can hold only up to 2 KB. To map string or character array larger than 2 KB, specify CLOB in the persistent-type attribute. You can map a byte array to BLOB. There is a size limitation of 4 KB when mapping a serialized object to BLOB type.Mapping java.sql.CLOB and java.sql.BLOB directly is not supported because these objects are not serializable.



Client for Departments Bean

import java.util.Hashtable;import javax.naming.Context;import javax.naming.InitialContext;import javax.rmi.PortableRemoteObject;...public class DepartmentsClient {

public static void main(String [] args){

DepartmentsClient departmentsClient = new DepartmentsClient();try{

Context context = getInitialContext();DepartmentsHome departmentsHome =

(DepartmentsHome)PortableRemoteObject.narrow(context.lookup("Departments"), DepartmentsHome.class);

Departments departments;...

Client for Departments BeanThe slide shows the client for the Departments bean. The client for a CMP entity bean is the same as the client for a BMP entity bean.Import the necessary packages. The slide shows only a few of the packages that are imported. The client application should have the following import statements:

import java.util.Hashtable;import javax.naming.Context;import javax.naming.InitialContext;import javax.rmi.PortableRemoteObject;import mypackage1.Departments;import mypackage1.DepartmentsHome;import java.util.Collection;import java.util.Iterator;import javax.naming.NamingException;

Note that the client application gets the initial context by invoking the getInitialContext() method, which is a private method of the bean. The implementation of this method is the same as in BMP beans. This method is not shown in this example. The lookup()method returns the reference to the home object (departmentsHome). This reference can now be used to create an EJB object. A variable of type Departments is declared.




System.out.println(" CREATING A NEW DEPARTMENT WITHID 404... ") ;

departments =departmentsHome.create(new Long(404),"Security");

System.out.println(" SUCCESSFUL ");System.out.println("Get the DEPARTMENT_NAME " +

departments.getDepartment_name());System.out.println("Changing the DEPARTMENT_NAME to

Security Services " );departments.setDepartment_name("Security Services");System.out.println("PRINTING THE DEPARTMENT_ID AND

DEPARTMENT_NAME");System.out.println(departments.getDepartment_id() +

" " + departments.getDepartment_name());...

Client for Departments Bean (continued)The code shown in the slide is the continuation of the client application. The client application:

• Invokes the create() method to create a new database data. One row with department_id 404 and department_name Security is added to the DEPARTMENTS table.

• Invokes the getDepartment_name() method to check if the department_name is Security

• Invokes the setDepartment_name()method to change the department_namefrom Security to Security Services

• Prints department_id and department_name




// Retrieve all instances using the findAll() methodCollection coll = departmentsHome.findAll();Iterator iter = coll.iterator();while (iter.hasNext()){departments = (Departments)iter.next();System.out.println("department_id = " +departments.getDepartment_id());

System.out.println("department_name = " +departments.getDepartment_name());

System.out.println("manager_id = " +departments.getManager_id());

System.out.println("location_id = " +departments.getLocation_id());

System.out.println();}

}catch(Throwable ex)

{...

Client for Departments Bean (continued)The client application can retrieve all instances by invoking the findAll() method. The code in the slide shows how to retrieve each field from the Collection by using an Iterator.



Summary

In this lesson, you should have learned how to:• Describe the features of a BMP entity bean• List the components that have to be created to

develop a BMP bean• Describe the features of a CMP entity bean• List the steps in developing a CMP bean• Develop and deploy a CMP bean• Develop a client for CMP EJB

SummaryIn this lesson, you should have learned that:

• The bean provider furnishes the logic to manage the persistence in case of BMP entity beans

• The container provides the persistence logic in CMP entity beansYou should have also learned how to develop a CMP bean and how to invoke the bean methods from a client application.




This practice covers the following topics:• Developing a CMP entity bean to represent and

update the EMPLOYEES table• Creating a remote interface, and a home interface

for a CMP entity bean by using Oracle JDeveloper 10g

• Implementing the create() methods, callback methods, and methods of the remote interface in the entity bean class

• Testing the entity bean with a client application

Practice 14-1: OverviewIn this practice, you develop a CMP entity bean by using Oracle JDeveloper 10g. This bean represents the EMPLOYEES table. You include a business method to update the EMPLOYEES table, and provide set() and get() methods for the CMP fields. You generate a client to test the entity bean.


Practice 14-1The purpose of this practice is to create a CMP entity bean (UpdateEmployee) that represents the EMPLOYEES table of the hr schema. The bean should contain the set()and get() methods for the CMP fields. It should also contain a business method called updateDetails() that updates the EMPLOYEES table.Note: For this practice, you can use the database connection hr, which was created in step 1 of practice 12-2. The workspace for this practice is practice14ske.jws. Open the updateemployeeCMP project. This project contains the necessary skeleton files for this practice. Note that these files are created by using the entity beans from the Tables option of JDeveloper, which was demonstrated in this lesson.

1. Navigate to UpdateEmployee.java in the UpdateEmployee bean and open it in the code editor. This is the remote interface: Declare an updateDetails()method, which takes the following as parameters: Long empid (this corresponds to employee_id, which is the primary key of the table), String lname, String fname, String email, Timestamp hdate, and String jid. This method should throw RemoteException.

2. Add code to the bean class. Open UpdateEmployeeBean.java in the code editor. Implement the updateDetails() method declared in the remote interface:

- Invoke the set() methods for the CMP fields lname, fname, email, hdate, and jid in the updateDetails() method.

3. Edit the UpdateEmployeeClient.java file:a. Import java.sql.Timestamp.b. Add code to the try block of the main() method. Use the second form of

create()method with parameters and add a new employee with the followingdata: employee_id=600, last_name=shenoy, email=pshenoy, hire_date=21-jul-2001, and job_id=ST_MAN Note: Observe the code that creates a Calendar object with the hire_date. Time in milliseconds is obtained with this object. Use this long value to create the Timestamp object while invoking the create()and updateDetails()methods. Pass the long value to the constructor of Timestamp. Other forms of constructors are deprecated.

c. After the record is added, use the set() method to set the first name to Preetham. Invoke the get() methods to display the first_name and last_name.

d. Invoke the updateDetails()business method to update the details of the employee. Change first_name to Joseph, last_name to Dsouza and email to jdsouza. Display the first_name and last_name.

e. Find details of the employee whose employee_id=120. Hint: Use findByPrimaryKey()method. Display the first_name and last_name of this employee.


Practice 14-1 (continued)4. Test and run the application:

a. Right-click UpdateEmployee bean and select Make (optional).b. Right-click the UpdateEmployee bean and select Run.c. Right-click the client application and select Run.

5. Sample Output:Adding a new employee with employee_id 600Added successfully...Calling setFirst_name() to set the first_name to PreethamDisplaying the first_name and last_name PREETHAM SHENOYCALLING THE updateDetails() BUSINESS METHOD TO UPDATE THEDETAILS OF THE EMPLOYEEDisplaying the first_name and last_nameJOSEPH DSOUZAFinding details of an employee whose employee_id=120, using the findByPrimaryKey() methodDisplaying the first_name and last_name MATTHEW WEISS


Container-Managed Relationships (CMRs)



Objectives

After completing this lesson, you should be able to do the following:• Define relationships between entity beans• Determine the cardinality and direction of a

relationship• Identify various elements of the deployment

descriptor that define the relationship• Develop CMR entity beans

ObjectivesIn a Java 2, Enterprise Edition (J2EE) application, it is not possible to implement the business logic in a single entity bean. It is practical to identify the smaller tasks and implement them using CMP entity beans. These entity beans may operate on persistent data that is related. You can capture such relationships with Container-Managed Relationships (CMR). This lesson introduces you to the steps of specifying a relationship between CMP entity beans. In this lesson, you create CMP beans that contain relationships of different cardinality and directionality.



Relationships

RelationshipsEnterprise applications typically deal with data in multiple tables. These tables are related and together constitute the complete data for the application. It is a challenging task to model the relationship between objects and tables in the database. Enterprise JavaBeans(EJB) 2.0 addresses this by introducing CMR. The slide shows the relationship between two tables: DEPARTMENTS and EMPLOYEES. Though only two tables are involved in the relationship, there can be multiple relationships established between them. Some of the relationships shown in the slide are:

• Departments may have one Employee• Departments may have many Employees• Employees may have one Departments



Implementing Relationships

• Data manipulation in the beans may involve a more complex data model, with a relationship between entity beans.

• The important aspects of a relationship are:– Cardinality: Number of data instances that can

participate in a relationship

– Direction: Direction in which a relationship is navigated

Implementing RelationshipsData manipulation in the beans may involve a more complex data model, with relationships between database tables or between entity beans. For example, more than one employee has the same job ID, or more than one employee works for a department. The relationship is specified through a foreign key in the database tables. How do you represent the data model between two entity beans, each of which represents one object within the relationship? In CMP beans, the container manages the relationship based on the relationship definition that is defined in the deployment descriptor. In BMP beans, the bean provider provides the logic for managing the relationship through callback methods. The important aspects of a relationship are cardinality and direction.



Cardinality and Direction of Relationships

• Cardinality:– One-to-one– One-to-many or many-to-one– Many-to-many

• Directionality:– Unidirectional– Bidirectional

Cardinality and Direction of RelationshipsCardinality: Cardinality is also referred to as multiplicity. Cardinality is the number of instances of data that can participate in a relationship. It refers to the number of entities on each side of the relationship. Cardinality can be of the following types:

• One-to-one relationship (1:1): There is exactly one-to-one mapping between the two objects that are involved in the relationship. For example, each employee has only one address and each address maps to only one employee.

• One-to-many relationship (1:M): This is the most common form of relationship. One row in the first object maps to many rows in the other object. For example, one department can have many employees but one employee can work for only one department.

• Many-to-many relationship (M:N): Many entities in each side of the relationship take part in an M:N relationship. For example, each employee may work on multiple projects and each project is assigned to many employees.


Cardinality and Direction of Relationships (continued)Direction: Direction in which to navigate a relationship. Direction applies to all cardinalities of the relationship. Direction can be of two types:

• Unidirectional: Unidirectional relationship is where you can navigate from entity A to entity B only. Navigation from entity B to A is restricted. Consider the example of browsing through a dictionary. If you have a word, you can look for the meaning or definition. But, you would not want to search for a word with its meaning or definition. If you design your relationship such that employees know their departments but departments do not know all the employees, then it is unidirectional.

• Bidirectional: Bidirectional relationship is where you can navigate from object A to object B and also in the reverse direction. If you design your relationship such that employees know their departments and the departments too know all the employees, then it is bidirectional. In simple terms, if you can find out the department of an employee with employee information and find the employee with department information, then it is bidirectional.



One-to-One Relationships

• The phone_num column is the foreign key in the EMPentity that is referencing the PHONE entity.

• Each employee has only one phone number and each phone number belongs to only one employee.

111 1111Smith100

phone_numnameemp_id

MCI650111 1111

servicearea_codephone_num

EMP

PHONE

One-to-One RelationshipsAssume that each employee has only one mobile phone number and each mobile phone number belongs to only one employee. The diagram in the slide shows this 1:1 relationship between the EMP and PHONE tables. The phone_num column is the foreign key in the EMPtable that is referencing the PHONE table.The association table helps in creating a relationship between nonassociated tables. You can create an association table for a relationship with any cardinality. For CMP beans with a one-to-many relationship, the server creates a default association table.



One-to-Many Relationships

Each department exists in only one location identified by location_id, whereas each location can contain many departments (1:M).

…Seattle1700…citylocation_id

DEPARTMENTS

LOCATIONS

1700Administration10

location_iddepartment_namedepartment_id

1700Purchasing30

One-to-Many RelationshipsIn the example in the slide, each department exists only at one location. But, each location can contain many departments. The diagram in the slide shows this 1:M relationship between the DEPARTMENTS and LOCATIONS tables. The location_id column is the foreign key in the DEPARTMENTS table that is referencing the LOCATIONS table. This column is also the primary key of the LOCATIONS table. For each key value in the LOCATIONS table, there may be more than one matching row in the DEPARTMENTS table.



Many-to-Many Relationships

Each employee may be assigned many jobs and each job may be assigned to many employees.

SA_REP176A1job_idemployee_idassign_pk

ASSIGNMENTS

EMPLOYEES

Jonathon176Nameemployee_id

JOBS_HISTORY

...SA_REP...job_id

Many-to-Many RelationshipsIn many-to-many relationships, more than one row from entity A maps to more than one row from entity B. For example, one employee can be assigned to more than one job and one job can be assigned to more than one employee. This type of a relationship is the most difficult to manage. In relational database design, the many-to-many relationships are normalized by introducing another table that contains foreign keys to both of the original tables. However, it is not mandatory to define an entity corresponding to the associating table, such as ASSIGNMENTS, when defining a many-to-many relationship between entity beans. The example in the slide shows the additional ASSIGNMENTS table that contains foreign keys that reference the EMPLOYEES table (employee_id column) and the JOBS_HISTORY table (job_id column).To understand this example better, consider an employee with employee_id 176. Check the job_id of this employee from the JOBS_HISTORY table. You will see two job IDs: SA_REP and SA_MAN. Now check the employees who have SA_REP as job_id in the EMPLOYEES table. The query will return 30 rows. Therefore, one employee can be assigned more than one job and each job can be assigned to more than one employee.



Oracle TopLink

Oracle TopLink run-time framework:• Facilitates data integration with enterprise

applications• Facilitates rapid development, deployment, and

execution of all persistence-related aspects of any Java application

SQL

RowsJava

application

JDBCTopLink

Oracle TopLinkOracle TopLink (TopLink) allows Java applications to access data stored in relational databases as objects. Application developers are able to work with relational databases much as they would in any Java application regardless of persistence.With TopLink, developers focus on the application and object model rather than the infrastructure of the database. TopLink can map Java objects to an existing (legacy) database or can suggest a new database schema from an object model (or vice versa). It provides a rich set of features to read, write, delete, and manage objects efficiently.The mature, robust persistence framework provided by TopLink significantly reduces the risk of using a relational database in a Java application.



TopLink: Integration of J2EE Applications with Data Sources at Run Time

DB2

SQL server

EIS

Oracle

XMLData mapping and integration

EJBs

Servlets/JSPs

J2EEApplication Server

TopLink: Integration of J2EE Applications with Data Sources at Run TimeIn general, TopLink works in any architecture.Entity Beans

• Bean-managed persistence (BMP) in any compliant application server• Container-managed persistence (CMP) in WebLogic and WebSphere

Java ObjectsTopLink can manage persistence of Java objects in any J2EE architecture. Moreover, because TopLink is written in Java, it will work in any compliant J2EE application server.



TopLink: Integrated with Oracle JDeveloper 10g

TopLink: Integrated with Oracle JDeveloper 10g TopLink is integrated with Oracle JDeveloper 10g. The TopLink Mapping Editor enables you to graphically configure TopLink deployment descriptors and map your Java classes and EJBs to database tables. You can create Java objects from tables or TopLink Mapping Descriptor as shown in the slide. You can reverse engineer your CMP EJBs by creating EJBs from tables. You can specify TopLink as the persistence manager while creating EJBs. When you select this option, the TopLink mapping structure is shown. This will help you identify the relationship between the fields of two entity beans.



Implementing Relationships

• Relationship restrictions:– Define only for CMP 2.0 entity beans– Declare related CMP beans in one deployment

descriptor– Use only local interfaces to define the relationship

• Define abstract get() and set() accessor methods in the bean class for each relationship field

• In the deployment descriptor, define:– Name of each relationship– Cardinality and direction for each relationship– One section for each side of a bidirectional

relationship– Cascade delete operations on one side of the

relationship

Implementing RelationshipsYou can define relationships only for CMP 2.0 entity beans. If you want to define relationship between two entity beans, then the entries for the relationship must be in the same deployment descriptor. The relationship between the CMP 2.0 entity beans is managed by the container. You must define only local interfaces for entity beans that take part in relationships.Defining relationships: You define a relationship in the deployment descriptor of the beans. There is only a single deployment descriptor for entity beans that take part in relationships. The deployment descriptor includes tags for information such as cardinality, direction, field name, field type, and so on. The methods that support the relationship defined in the deployment descriptor are included in the local interface and the bean class.The entity beans that take part in relationships can have only local interfaces. These local interfaces must have setter and getter methods corresponding to name of the fields. For example, consider a unidirectional one-to-one relation: an employee can have only one address. You will design two beans: employee bean and address bean. To define the relationship, the local interface of the employee bean should have the getAddress()and setAddress(Address ad)methods. These methods must be included in the implementation class as abstract methods. These methods are implemented by the container.



Defining Abstract Accessor Methods

• Name:– get<cmrfieldname> and set<cmrfieldname>– Example: getDepartment(),

setEmployees(EmpLocal emp)

• Return type:– Local interface of the target bean for single object

retrieval– Collection or set of local interface objects for multiple

object retrieval• Location where it is defined:

– Only in the source bean for unidirectional relationship– In both beans for bidirectional relationship

Defining Abstract Accessor MethodsEach relationship field must have the abstract accessor methods defined for it.The name of an accessor method for a CMR field starts with get or set and is followed by the CMR field name (with an uppercase initial letter). For example, if a CMR field that represents an entity bean is department, then the get()accessor method would be getDepartments(). If you have defined only get()methods in the local interface, then these fields are considered read-only fields. However, the implementation class should have both set and get methods. In the bean class, the setter and getter methods for the CMP fields are abstract (without implementation) because the EJB container implements them. The bean developer must explicitly code the details to implement the relationship in BMP beans.In a relationship that sets or retrieves only a single entity, the object type that is passed back and forth must be the local interface of the target entity bean. In a relationship that sets or retrieves multiple objects, the object type passed back and forth is a Set or Collectioncontaining local interface objects.For a unidirectional relationship, only the source bean defines the abstract accessor methods for the target bean. In a bidirectional relationship where both beans can access each other, each bean defines the accessor methods for the other bean.For entities in one-to-one and many-to-many relationships, either of the entities can be the source entity. For entities in one-to-many relationships, the entity on the “one” side is the source. For entities in many-to-one relationships, the entity on the “many” side is the source.



Accessor Methods in 1:1 Relationships

For bidirectional relationships, define abstract get()and set() accessor methods for CMR fields in both the abstract bean classes.public abstract class Emp implements EntityBean {...public abstract PhoneLocal getPhone_PhoneNo();public abstract void setPhone_PhoneNo(PhoneLocal p);...

public abstract class Phone implements EntityBean {...public abstract EmpLocal getEmp_EmployeeID();public abstract void setEmp_EmployeeID(EmpLocal e);...

Implementing 1:1 RelationshipsThe container manages relationships by implementing the abstract accessor methods that are defined in the abstract bean class corresponding to the CMR fields that are specified in the deployment descriptor. The bean developer provides a null implementation for the ejbLoad()and ejbStore()methods, unlike in BMP beans. The code in the slide defines the relationship between the Emp and Phones CMP entity bean classes. Both the Emp and the Phone beans declare the get() and set() accessor methods for each other because they have a bidirectional relationship. If there is a unidirectional one-to-one relationship between the beans, then only the bean at the source side of the relationship (Emp) declares the accessor methods.Note: Note that the CMR field names need not be the same as the names of the entity beans.



Accessor Methods in 1:M Relationships

public abstract class DepartmentsBean implementsEntityBean{...public abstract LocationsLocal getLocations_locationId();public abstract void setLocations_locationId(LocationsLocal locations_locationId);

...

public abstract class LocationsBean implements EntityBean{...public abstract Collection getDepartments_locationId();public abstract void setDepartments_locationId(Collectiondepartments_locationId);...

Accessor Methods in 1:M Relationships The code in the example shows a one-to-many bidirectional relationship between the Departments and the Locations entity beans. Because each department can exist only in one location, the Departments bean uses a single Locations local interface object in its accessor methods on the Locations entity. Because there can be many departments in a location, the Locations entity bean uses a collection of Departments local interface objects in its accessor methods on the Departments entity. You can also use Set instead of Collection.In a many-to-many bidirectional relationship, both the source and the target beans define accessor methods for each other and use a collection of local interface objects.



Checking Relationship Mappings in JDeveloper

Checking Relationship Mappings in JDeveloperAfter you have created the entity beans that take part in the relationship, you can check the relationship mappings. Right-click the bean and select Edit CMP mappings. Click the Relationship Mappings tab to see the mappings. The slide shows the relationship mappings of the Departments and Locations entities.



Accessor Methods in M:N Relationships

public abstract class EmployeesBean implementsEntityBean{ ...public abstract Collection getJobHistory_employeeId();public abstract void setJobHistory_employeeId(Collection jobHistory_employeeId);... }

public abstract class JobHistoryBean implements EntityBean { ...public abstract Collection getEmployees_employeeId();public abstract void setEmployees_employeeId(Collection employees_employeeId);... }

Accessor Methods in M:N Relationships In the CMP bean implementation, each table involved in the M:N relationship is represented by a CMP entity bean. The partial code example in the slide shows the accessor methods for the Employees and JobHistory many-to-many related entities.



Implementing a Relationship inthe Deployment Descriptor

Implementing a Relationship in the Deployment DescriptorThe slide shows key elements in the deployment descriptor to represent the relationship between two entity beans that are participating in the relationship. You define the relationships between entity beans in the same deployment descriptor where the entity beans are declared. <relationships> is the main element. All relationships are defined within this element and, therefore, this element encloses information on multiple relationships.The <ejb-relation> element contains definition of each specific entity-to-entity relationship. <ejb-relation-name> is an optional descriptive tag and holds a short name to identify the relationship.<ejb-relationship-role> declares relationship details for each side of the relationship. Each <ejb-relation> element will have two <ejb-relationship-role>elements: one for each side of the relationship. These elements enclose important details such as multiplicity, cardinality, and CMR fields.


Implementing a Relationship in the Deployment Descriptor (continued)<ejb-relationship-role-name> is an optional descriptive tag that describes each side of the relationship. Observe the first <ejb-relationship-role-name> element in the slide. It includes the description “Employees-owned-by-departments_departmentId.”The description clearly indicates that many employees can work in a department or many employees can have a particular department ID entry in the department_id field.<multiplicity> element defines the type of relationship: 1:1, 1:M, or M:N. The value for this tag is either One or Many. Considering the relation discussed above, many employees can work in a department and, therefore, the multiplicity must be Many. The <relationship-role-source> element defines the EJB that the relationship maps to. The <cmr-field> element defines the name and type of the CMR field. The parent entity of the relationship must declare this element. If the child entity also has a <cmr-field> element, then it is a bidirectional relationship. The type of this field can be a Collection or a Set or a single local interface object, depending on the multiplicity of the relationship.



Implementing 1:1 Relationships

...<relationships><ejb-relation>

<ejb-relation-name>EMP-PHONE</ejb-relation-name><ejb-relationship-role>

<ejb-relationship-role-name>Emp-has-Phone

</ejb-relationship-role-name><multiplicity>One</multiplicity><relationship-role-source><ejb-name>Emp</ejb-name>

</ relationship-role-source><cmr-field>

<cmr-field-name>Phone</cmr-field-name><cmr-field-type>PhoneLocal</cmr-field-type>

</cmr-field></ejb-relationship-role>

...

Emp to Phone

Implementing 1:1 Relationships The slide shows the partial deployment descriptor that is used to represent the relationship between the Emp and Phone entities, which are defined under one ejb-jar section. The EJB details of both the beans are described under separate <entity> sections of the <enterprise-beans> section.The <ejb-relation> element for these two entities contains two <ejb-relationship-role> sections, one for each of the beans. In a unidirectional relationship, you define this section only from the source bean.The <multiplicity> element in the above example indicates that the cardinality of the relationship from the Emp entity to the Phone entity is one.The <cascade-delete/> tag specifies that if the Emp entity is deleted, then the related Phone entity (a row from the database) also be deleted. The <cmr-field> section defines the name and type of the CMR field, which is the target entity bean. In the example, the CMR field for the Phone entity is of the PhoneLocaltype.



Implementing 1:1 Relationships

...<ejb-relationship-role>

<ejb-relationship-role-name>Phone-has-Emp

</ejb-relationship-role-name><multiplicity>One</multiplicity><cascade-delete /><relationship-role-source><ejb-name>Phone</ejb-name>

</ relationship-role-source><cmr-field>

<cmr-field-name>Emp</cmr-field-name><cmr-field-type>EmpLocal</cmr-field-type>


</ejb-relation></relationships> ...

Phone to Emp

Implementing 1:1 Relationships (continued)The deployment descriptor tags in the slide show the EJB relationship role from the Phoneentity’s side. Multiplicity from the Phone entity side is also one. Thus, this is a bidirectional 1:1 relationship.<cascade-delete/>: In many situations, child data has no meaning without parent data. If a parent is deleted from the system, then the child record should also be deleted. You can specify this behavior by using the <cascade-delete/> tag. The tag can only be assigned to a child entity bean with a multiplicity of one or many that has a parent with a multiplicity of one. The <cascade-delete/> tag in the example clearly indicates that if an EmpBean is removed, then a PhoneBean should also be removed. If an employee’s details is removed from the emp table, then the employee’s phone details must be removed from the phone table.



Implementing 1:M Relationships

<relationships><ejb-relation><ejb-relation-name>Departments-Locations</ejb-relation-name> <ejb-relationship-role><ejb-relationship-role-name>Locations-has-

departments_locationId</ejb-relationship-role-name><multiplicity>One</multiplicity><relationship-role-source><ejb-name>Locations</ejb-name>

</relationship-role-source><cmr-field><cmr-field-name>departments_locationId</cmr-field-name><cmr-field-type>java.util.Collection</cmr-field-type>

</cmr-field></ejb-relationship-role>...

Departments to Locations

Implementing 1:M Relationships The deployment descriptor tags in the slide show a one-to-many relationship between the Departments and Locations entities. This shows the details of one side of the relationship. You can understand the relationship by looking at the <ejb-relationship-role-name> tag. The tag indicates that one department can have only one location ID. That is, a department can exist in only one location and, therefore, the multiplicity is one.



Implementing 1:M Relationships

...<ejb-relationship-role><ejb-relationship-role-name>Departments-owned-by-locations_locationId

</ejb-relationship-role-name><multiplicity>Many</multiplicity>

<relationship-role-source><ejb-name>Departments</ejb-name>

</relationship-role-source><cmr-field><cmr-field-name>locations_locationId</cmr-field-name>


...

Locations to Departments

Implementing 1:M Relationships (continued)The deployment descriptor tags in the slide show the “many” side of the relationship between the Locations and Departments entities. The multiplicity specifies that each location can contain many departments.



Implementing M:N Relationships

...<ejb-relation>

<ejb-relation-name>JobHistory – Employees</ejb-relation-name><ejb-relationship-role><ejb-relationship-role-name>

JobHistory-has-employees_employeeId</ejb-relationship-role-name>

<multiplicity>Many</multiplicity><relationship-role-source><ejb-name>JobHistory</ejb-name>

</relationship-role-source><cmr-field><cmr-field-name>employees_employeeId</cmr-field-name><cmr-field-type>java.util.Collection</cmr-field-type>


...

Implementing M:N RelationshipsThe deployment descriptor tags in the slide show the relationship between the JobHistory and Employees entities. The multiplicity specifies that many employees can be assigned many jobs. Looking at the <ejb-relationship-role-name> and <multiplicity> tags, you can interpret the relation as the JobHistory entity can have multiple occurrences of employee ID. Because many employees can be assigned to a job, the result of the CMR get() accessor method would be a Collection of EmployeesLocal local interface objects.Note: You cannot specify <cascade-delete/> with many-to-many relationships because there is no single row on which another row is dependent. For example, in a one-to-many relationship between Departments and Locations, for one location, there are many departments. If you delete one master location, you can choose to delete all the child department rows. In a many-to-many relationship between Employees and JobHistory, if you delete one job you cannot delete employees working on that project, because the employees can work on more than one project and, thus, should be retained in the table.



Implementing M:N Relationships

<ejb-relationship-role><ejb-relationship-role-name>Employees-has-jobHistory_employeeId

</ejb-relationship-role-name><multiplicity>Many</multiplicity><relationship-role-source><ejb-name>Employees</ejb-name>

</relationship-role-source><cmr-field><cmr-field-name>jobHistory_employeeId</cmr-field-name><cmr-field-type>java.util.Collection</cmr-field-type>


Implementing M:N Relationships (continued)The tags in the slide show the other side of the relationship between the JobHistory and Employees entities.



Mapping Relationship Fields to Database

• Accept default mapping provided by container (specify relationship fields in ejb-jar.xml)

• Explicitly map the fields to existing table columns in orion-ejb-jar.xml

Mapping Relationship Fields to DatabaseEach entity bean maps to a table in the database. Each of its persistent and relationship fields are saved within a database table in columns. To map these fields to a database, you must either:

• Accept the defaults for these fields and avoid more deployment descriptor configuration, (The default mapping for relationship fields is similar to the mapping for CMP fields, discussed in the lesson titled “Achieving State Management in the Business Tier.”) or

• Map the fields to the columns in a table that already exists in a designated database. Persistent data mapping is configured within the orion-ejb-jar.xml file.



Default Mapping of Relationship Fields

• Database: Specified in data-sources.xml• Each table in relationship: Same as for CMP entity• Columns in each table: Based on <cmr-field>,

which represents a bean in the relationship• For each <cmr-field> of an entity, the container

creates a foreign key to the primary key of the related entity:– In the source bean table for one-to-one mapping– In a container-generated association table for one-

to-many and many-to-many relationships• User-defined or automatically generated primary

key

Default Mapping of Relationship FieldsThe database is specified in the data-sources.xml file. One table is created for each entity in the relationship. Similar to the CMP bean table, the table name is a unique combination of EJB name, Java Archive (JAR) file, application name, an underscore, and a five-character hash code.The container generates columns in each table based on the <cmp-field> and <cmr-field> elements. Each <cmp-field> is a column that relates to the entity bean data. Each <cmr-field> element represents a relationship (entity). For each <cmr-field> element, the container creates a foreign key that points to theprimary key of the related entity object, as follows:

• In a one-to-one relationship, the foreign key is created in the database table for the source EJB and is directed to the primary key of the target database table.

• In one-to-many, many-to-one, and many-to-many relationships, an association table (third table) is created. The association table contains two foreign keys, each pointing to the primary key of one of the entity tables.

The translation rules for converting Java data types to database data types are defined in the specific database XML file, such as oracle.xml, located in j2ee/home/config/database-schemas.


Default Mapping of Relationship Fields (continued)Both entity tables contain primary keys. The primary key can be defined or automatically generated. A defined primary key is generated as designated in the primary key class or as a simple data type. If you specify java.lang.Object as the primary key class type in <prim-key-class>, but do not specify the primary key name in <primkey-field>, then the primary key is automatically generated by the container.



Explicit Mapping of Relationship Fields

1. Deploy your application with only the ejb-jar.xml elements configured.

2. Copy the container-created orion-ejb-jar.xmlfile to your development environment.

3. Modify the <entity-deployment> element in the orion-ejb-jar.xml file to use the database table and columns that you specify.

4. Rearchive and redeploy your application.

Explicit Mapping of Relationship FieldsYou can explicitly map the relationships between entity beans within an existing database table and its columns in the orion-ejb-jar.xml file. The process is similar for CMP field mapping. The steps for explicit mapping are listed in the slide.Note: The above-mentioned method is simple and is a common practice for specifying explicit mapping. You need not deploy your application first to obtain the orion-ejb-jar.xml file. You can create an orion-ejb-jar.xml file from the beginning along with other files in your application and deploy the files together. For more information about default mapping and explicit mapping, see the OC4J Enterprise JavaBeans Developer’s Guide.



Using JDeveloper to Create CMR Beans

Using JDeveloper, you can create a container-managed relationship between entity beans in the following ways:• Create CMP beans from tables and generate

default relationships between entities.• Use the EJB Module Editor to specify the

relationship or use TopLink Mapping Editor.• Create an EJB Diagram for CMP beans and

generate default relationships.

Using JDeveloper to Create CMR BeansUsing JDeveloper, you can create relationships between entity beans while creating the entities. You can also create relationships by using the EJB Module Editor or TopLink Mapping Editor.You can create an EJB Diagram and drag database tables to the diagram. The default relationships are generated.



Summary

In this lesson, you should have learned how to:• Determine the cardinality and direction of a

relationship• Define and implement relationships between CMR

entity beans

SummaryIn this lesson, you should have learned about the different types of relationships that can be established between entity beans. You have also learned about the various tags of the deployment descriptor that determine the relationship.



Practice 15: Overview

This practice covers creating a one-to-many relationship between the Employees and Departments entity beans.

Practice 15: OverviewIn this practice, you will use Oracle JDeveloper 10g to create Employees and Departments entity beans with a one-to-many relationship.


Practice 15-1The purpose of this practice is to create Employees and Departments entity beans with a one-to-many relationship. The workspace for this practice is practice15ske.jws. Open the empdeptCMR project. This project contains the two entity beans: Employeesand Departments. Note: You will use the database connection hr, which you have used for the lesson 14 practice.

1. Expand the empdeptCMR project and double click DepartmentsBean.java in the Structure Pane to open it in the editor. Examine the various methods in this class and observe that all the set() and get() methods are abstract methods. You will use the following method in your application:

public abstract Collection getEmployees_departmentId();2. Similarly, observe the methods in EmployeesBean.java. You will use the

following method in your application:public abstract DepartmentsLocal getDepartments_departmentId();

3. Create a session bean named EmpdeptSession containing a remote interface. Enter EmpdeptSession for the EJB Name and accept all other defaults.

4. Add EJB Local References of Employees bean and Departments bean to the session bean by following these steps:

a. Double-click EmpdeptSession to open the EJB Module Editor.b. Select EJB Local References and click Add.c. Select Departments from the “Auto-create Reference to EJB” drop-down

menu and click OK.d. Click Add again and select Employees from the “Auto-create Reference to

EJB” drop-down menu and click OK.e. Click OK to close the EJB Module Editor.f. Double-click EmpdeptSessionBean.java and see the lookup code that is

added as a result of adding EJB Local References to EmpdeptSession.5. Create Data Transfer Object (DTO) for both Employees and Departments entity

bean by right-clicking the bean and selecting Generate Data Transfer Object.Note: Refer to the last page of this lesson to learn about DTOs.

6. Edit the remote interface, EmpdeptSession.java, of the session bean. Import the following: java.rmi.RemoteException and java.util.Collection. Add a method called getEmployeesInDept()that takes a Long value as argument and returns a Collection.

7. Include another method getDepartmentID()that takes a Long value as argument and returns an object of Long.


Practice 15-1 (continued)8. Edit the EmpdeptSessionBean.java session bean. Import java.util.*.

Implement the getEmployeesInDept() method as follows:import java.util.*;...public Collection getEmployeesInDept(Long deptno)

{Collection returnColl = new ArrayList();try {DepartmentsLocal dept = this.getDepartmentsLocalHome().findByPrimaryKey(deptno);

// get all the employees in the particular department. // Note that you are invoking the method// getEmployees_departmentId() of the Departments bean

Collection empColl = dept.getEmployees_departmentId();

// create an iterator for the collection that is returned

Iterator empIter = empColl.iterator();while(empIter.hasNext()) {

// create the DTO object, get the necessary values from // the bean and populate the DTO object with those values// using the set methods.

EmployeesLocalDTO empDTO = new EmployeesLocalDTO();EmployeesLocal empBean = (EmployeesLocal)empIter.next();empDTO.setEmployeeId(empBean.getEmployeeId());empDTO.setFirstName(empBean.getFirstName());empDTO.setLastName(empBean.getLastName());

// add the DTO object to the collection

returnColl.add(empDTO);}}

catch(Exception ex) {

System.out.println(" Error getting employees in dept : "+deptno+" "+ex);

}

// return the collection to the client

return returnColl;}


Practice 15-1 (continued)9. Implement the getDepartmentID()method as follows:

public Long getDepartmentID(Long empno){Long deptno=new Long(0);

try{EmployeesLocal emp =this.getEmployeesLocalHome(). findByPrimaryKey(empno);

deptno = emp.getDepartments_departmentId(). getDepartmentId();

}catch(Exception ex){System.out.println(" Error getting the

department_idof employee ");

}return deptno;

}

10. Create the client application. Right-click the session bean and select New Sample Java Client. Select Connect to OC4J Embedded in JDeveloper and click OK.

a. Edit the client and import java.util.*.b. In the main()method, use the session bean instance to invoke the

getEmployeesInDept()to get the information of all employees working in department 50. Note that this method in turn invokes the getEmployees_departmentId()method of the Departments bean.

c. Create an Iterator to iterate through the collection that is returned by the session bean. Typecast the object in the Iterator to EmployeesLocalDTO, retrieve the values, and print the values. Repeat this for all the objects in the collection.

d. Invoke the getDepartmentID()method to get the department ID of the employee with employee_id 118. Note that this method in turn invokes the getDepartments_departmentId() method of the Employees bean.

11. Right-click EmpdeptSession and select Run.

12. Right-click EmpdeptSessionClient and select Run.


Practice 15-1 (continued)Sample Output:

PRINTING EMPLOYEE_ID, FIRST_NAME, LAST_NAME OF EMPLOYEES IN THE DEPARTMENT 120 Matthew Weiss121 Adam Fripp122 Payam Kaufling123 Shanta Vollman124 Kevin Mourgos......

PRINTING DEPTNO OF THE EMPLOYEE: 30

Data Transfer Object (DTO)Session beans and entity beans are categorized as server-side business components. When a client invokes a method of an entity bean through a session bean, certainly the method returns data to the client. The client may invoke multiple methods to get all the required values. The client usually is a remote client and, therefore, the question of efficient data transfer across the network comes up. You can design your business component in such a way that it returns a collection of primitive types, but this is not practical and will not serve the business needs. So it is better to use a serializable object that encapsulates all the business data that has to be passed to the client. This object will have the set() and get() methods for all the variables associated with a bean. A single method call is required to transfer the object to the client. This object is called a Data Transfer Object. The client invokes a single method of the bean (typically, session bean) instead of invoking multiple methods to get values. The bean constructs a new DTO, populates the object with all the values, and returns it to the client. The client receives the object and invokes the get() methods to retrieve the values. The advantage here is that the object is now available with the client and, therefore, all calls to the object are local calls instead of remote method invocations.


Developing Message-Driven Beans



Objectives

After completing this lesson, you should be able to do the following:• Describe the need for a message-oriented

middleware (MOM) type• Define Java Message Service (JMS)• Describe and create a message-driven bean (MDB)• Differentiate between a stateless session

Enterprise JavaBean and a message-driven bean• Configure JMS resource provider

ObjectivesThis lesson explains the necessity of asynchronous message delivery, and shows how a message-driven EJB can be developed, deployed, and used to process asynchronous messages. This lesson also provides an introduction of JMS and different MOM types to make the concept of message-driven beans more clear.



Overview of Messaging Systems

• Messaging is a way for software components and/or applications to communicate.

• Messaging systems are peer-to-peer in nature.• Clients can send or receive messages from other

clients.• JMS was designed to allow applications to create,

send, and receive messages synchronously or asynchronously.

• Java Message Service allows access to existing MOM services, such as the OC4J in-memory JMS server.

Overview of Messaging SystemsMessaging systems have been around for many years in various forms. For example, an e-mail system is a form of messaging system. However, e-mail messaging is used for communication between a human user and a software system.In the J2EE world, messaging systems are used for communication between different software components or applications. They are a way for programmatically generating messages to be sent to another program.The JMS API was designed to facilitate communication between applications, and supports the creation, sending, and receiving of synchronous and asynchronous messages.To enable messages to be communicated between JMS clients, middleware is required to register destinations for messages that are published by clients, and from which a message can be received by other client applications. Typically, existing MOM services, such as the OC4J JMS server, or IBM’s MQSeries software, can be used for such purposes.The JMS API was designed to be independent of vendor-specific MOM services. MOM services are usually used as JMS providers.



Types of Message Consumption

Messaging systems are inherently asynchronous, but JMS allows messages to be consumed in two ways:• Synchronously

– Receiver thread blocks until a message can be consumed or times out.

– Receiver acknowledges message receipt.– There is tightly coupled interaction.

• Asynchronously– Receiver listens for messages. When a message is

delivered, the listener message handler is invoked.– Receiver thread does not block.– There is loosely coupled interaction.

Types of Message ConsumptionMessaging systems are typically asynchronous, thereby allowing message delivery and receipt, which are independent of each other. JMS provides for synchronous or asynchronous message consumption.Synchronous Message ConsumptionClients (receivers) explicitly read messages from a destination. The receiving process blocks until a message arrives or a time out occurs. This model is similar to an EJB using RMI, where the client invokes a bean method; the bean processes the request and sends the result back to the client. If the bean and its interfaces are not available (for example, the server is down), then the client is unable to complete its operation. Synchronous messaging has the sender waiting for acknowledgment of receipt from the receiver. This model has a producer send only one message to one receiver at a time, and there is a tight coupling between the sender and the receiver.


Types of Message Consumption (continued)Asynchronous Message ConsumptionIn asynchronous messaging, senders do not wait for acknowledgement of receipt from the receiver. A receiver registers itself to listen for a message and is notified by an event when it is delivered. The receiver’s listener invokes a handler process on the arrival of the message. For example, a stock ticker need not wait for an acknowledgement from its receivers before broadcasting the stock quotes. In the asynchronous model, messages can be produced for more than one receiver at a time (that is, the sender and the receiver are not directly connected). Therefore, there is no blocking of threads in an asynchronous messaging system. This produces a loose coupling between the sender and the receiver.



Java Message Service (JMS)

• Is a J2EE standard messaging system• Can guarantee message delivery• Supports messaging across multiple platforms• Supports two models of communication

– Point-to-point model– Publish-and-subscribe model

Client application

Messaging API

MOMJMS client JMS client

Java Message Service (JMS)JMS is a Java 2, Enterprise Edition (J2EE) API that is used to access enterprise-messaging systems and send asynchronous messages. The enterprise messaging system (message-oriented middleware, or MOM) enables transfer of messages among different applications over the network. By using MOM, you can send a message from one platform and receive it on a different platform. This model also supports guaranteed message delivery. Client applications communicate with each other using messaging APIs. Messaging clients send and receive messages through MOM.JMS supports two models for the communication of messages:

• The point-to-point model, also known as the PTP model, is based on a queue structure. This model is popular where there is one message consumer for a message.

• The publish-and-subscribe model, also known as the pub/sub model, is based on a topic structure. This model is popular when a message is to be delivered to more than one consumer, such as when broadcasting a message to multiple clients.



JMS Application Architecture

The main components of a JMS application are:• JMS clients• JMS provider• Administered objects (in the Java Naming and

Directory Interface [JNDI] namespace)– Connection factories– Destinations (queues or topics)

JMS provider

Queue/Topic

JMS client

JMS Application

Consumer

JMS client

JMSApplication

Producer

JMS Application ArchitectureThere are different participants or components of a JMS application. A JMS client is any Java application that participates in a JMS environment. A JMS client can receive and produce messages.

• A JMS producer produces (sends) messages and is also known as a “publisher.”• A JMS consumer receives (requests) messages and is also known as a “subscriber.”

A JMS provider handles the routing and delivery of messages. Oracle provides a JMS provider in its application server and database server.Administered objects, stored in the JNDI namespace of a J2EE container, consist of:

• Connection factories: Used by a client to create a connection with a provider• Destinations: Targets of messages that are produced, or sources of messages that are

consumed by client applications, such as queues for the JMS PTP model and topics for the JMS pub/sub model

A JMS application generally contains one JMS provider and more than one JMS client. The messages are sent through a messaging system called the message broker, or MOM services. The OC4J JMS, Oracle JMS, BEA’s WebLogic JMS, Sun Microsystems’ iPlanet Message Queue, and IBM’s MQSeries are some examples of JMS providers.



Point-to-Point Model

• Senders send messages to virtual destinations.• There is only one receiver for a message from a

queue.

Queue senderM* - Message

Queues (virtual destinations)

Queue receiver

R3

R2

M1

M2

M3

Messaging server

M1

M3

Queue1

Queue2

M2

S1

S2

R1

Point-to-Point ModelIn the PTP model of communication, a sender sends messages to virtual destinations known as “queues.”A sender can send one or more messages. JMS clients who are interested in receiving the messages subscribe to queues of interest and receive messages from those queues. The sender does not wait for acknowledgment from the receiver after sending its messages. One queue can have more than one sender sending the messages and more than one receiver receiving the messages. However, one message can be delivered to only one receiver from the queue. The receiver has to pull the message that arrived at this queue.Note: The JMS specification does not define the method of distribution of messages among the receivers for a queue. It only requires the guarantee of the message delivery. Therefore, it is important to ensure that only eligible clients subscribe and receive messages from a particular queue.MDBs can make use of the PTP model of communication. However, they are more commonly designed to use the publish-and-subscribe model that is discussed in subsequent slides.



Publish-and-Subscribe Model

• Publishers send messages to virtual destinations.• One or more subscribers receive the messages.

Topic subscriber

S3

S2

S1M1

M2

M1

M2P2

Topic1P1

Topics (virtual destinations)

Topic publisherM* - Message

Messaging server

Topic2

Publish-and-Subscribe ModelIn the publish-and-subscribe (pub/sub) model of communication, a publisher sends messages to virtual destinations known as “topics.” A publisher can send one or more messages to a topic. JMS clients who are interested in receiving the messages subscribe to the topics of interest and receive messages from those topics. The publisher need not wait for acknowledgment from the subscribers to publish its messages. One topic can have more than one publisher and more than one subscriber. The messages that arrive to this topic are automatically sent to the subscribers. The publisher is not concerned whether there are any subscribers receiving the messages. A subscriber for a topic can specify a filter (for example, to receive only messages of priority 1). A topic subscriber may request either a durable or nondurable subscription. A durable subscription ensures that the message is delivered to the subscriber whenever it is active. That is, if a subscriber is not connected to the system when the message was broadcast, the message broker ensures that the subscriber receives the message whenever it is active. Examples for pub/sub model communication are stock quote broadcasting and airline arrival and departure information.



Using JMS Interfaces

The JMS API service uses the following objects and interfaces that are located in the javax.jms package:• JMS-administered objects:

– Connection Factory: Creates connections– Destination: Target/source of messages

• Connection: Creates sessions• Session: Creates a message producer or

consumer• Message Producer: Sends to a destination• Message Consumer: Receives from a destination• Message: The body of the information to be

communicated

Using JMS InterfacesThe JMS API provides interfaces for the production and consumption of messages. The message provider (or infrastructure) must be first configured to hold connection factories and destinations, as created by server administrators, by specifying them in XML deployment descriptors.An application uses the connection factory interfaces to open a connection to the JMS provider, through one of the following two types of connection factory interfaces:• javax.jms.QueueConnectionFactory (for the point-to-point model)• javax.jms.TopicConnectionFactory (for the publish/subscribe model)

The queue interfaces in the javax.jms package are:• QueueConnection: Created from a QueueConnectionFactory• QueueSession: Created from a connection for producers and consumers to interact• QueueSender: Created from a session to produce messages on a Queue• QueueReceiver: Created from a session to consume messages from a Queue• Queue: Is the destination for messages


Using JMS Interfaces (continued)The topic interfaces in the javax.jms package are:• TopicConnection: Created from a TopicConnectionFactory• TopicSession: Created from a connection to publish and subscribe to a Topic• TopicPublisher: Created from a session to publish messages to a Topic• TopicSubscriber: To subscribe to a session and consume messages from a

Topic• Topic: Is the destination of messages

A Message object can be sent to a queue, or published to a topic, and received by the consumer.

Choosing Between the Two ModelsA JMS application can use both models: PTP for some messages and pub/sub for other messages. The JMS 1.0.2 specification does not require a JMS provider to support both the models. The EJB 2.0 specification requires the EJB server vendor to support both the models.Generally, you use the pub/sub model when your message needs to be broadcast to more than one subscriber. Using this model allows subscribers to filter the messages that they receive. Use the PTP model when your message needs to be processed by only one receiver.



JMS Message Structure

JMS messages are composed of the following parts:• A header containing a common set of header

fields– Field examples: JMSMessageID and

JMSDestination

– Field values are used by clients and providers for identification and routing information.

• Properties for application-defined property values, which can be used for message filtering purposes

• A body for the contents of the message, whose contents can be structured as a StreamMessage, MapMessage, TextMessage, ObjectMessage, or ByteMessage

JMS Message StructureA message structure has the following components:

• A header that has standard fields such as JMSMessageID and JMSDestinationfor the destination, priority of the message, and so on

• Properties of the message such as any user-defined name-value pairs of properties• Message body, which contains the actual message. The five types of messages are:

- TextMessage for a simple string. Methods: getText() and setText()- MapMessage for an unordered set of name string and values pairs. Values can

be primitive types. Methods: get() and set() methods for different Java types.

- BytesMessage for a stream of bytes (uninterpreted)- StreamMessage for a stream of primitive values serially processed- ObjectMessage for a serialized Java object. Methods: getObject() and

setObject()

The javax.jms.Message interface—a superinterface for the five message types—can be used to send a message with an empty body. The Message interface defines the get()and set() methods to manage message contents. For more information, refer to the JMS API documentation.A JMS client can filter the message that it receives by specifying conditional expressions in the message selector, using standard header fields or application-defined property values.



Sending a Message to a Queue

The code steps to send a message to a JMS queue are:1. Connect to the naming server using JNDI.2. Obtain a QueueConnectionFactory.3. Obtain the name and location of Queue.4. Open a QueueConnection and start it.5. Create a QueueSession.6. Create a QueueSender from the session.7. Create the Message and set the header, body, and

properties.8. Send the message and close resources.

Sending a Message to a QueueThe slide shows the sequence of steps involved in sending a message to a JMS queue. The code example listed here demonstrates these steps:Context ctx = new InitialContext();QueueConnectionFactory cf = (QueueConnectionFactory) ctx.lookup(

"java:comp/env/jms/QueueConnectionFactory");QueueConnection conn = cf.createQueueConnection();conn.start();QueueSession sess = conn.createQueueSession(false,

Session.AUTO_ACKNOWLEDGE);Queue queue = (Queue) ctx.lookup("java:comp/env/jms/demoQueue");QueueSender sender = sess.createSender(queue);TextMessage message = sess.createTextMessage();message.setLongProperty("msgid", msgId);message.setText("Hello World");sender.send(message);sender.close();sess.close();conn.close();

Note: The code should be enclosed in an appropriate try/catch block.


Sending a Message to a TopicThe following are the steps for publishing a message to a JMS topic, which are similar to those for sending a message to a queue:

1. Connect to the naming server by using JNDI.2. Obtain a connection factory for the JMS provider that hosts the desired topic.3. Obtain the name and location of the topic.4. Open a connection to the JMS provider by using the connection factory.5. Create a JMS session and obtain a topic object by using the JMS session.6. Create a topic publisher that is used to publish messages.7. Create the message that is to be published.8. Publish the message to the topic.

Here is a code snippet of publishing a message to an OC4J JMS topic:Context ctx = null;TopicConnectionFactory cf = null;TopicConnection conn = null;TopicSession sess = null;Topic topic = null;TopicPublisher publisher = null;TextMessage message = null; ctx = new InitialContext();cf = (TopicConnectionFactory) ctx.lookup(

"java:comp/env/jms/TopicConnectionFactory");topic = (Topic)

ctx.lookup("java:comp/env/jms/demoTopic/topic1");conn = cf.createTopicConnection();sess = conn.createTopicSession(true, Session.AUTO_ACKNOWLEDGE);publisher = topicSess.createPublisher(topic);message = sess.createTextMessage();message.setText("Hello World");publisher.publish(message);



Receiving Messages

The following are the steps to receive a message from a topic for non-MDB applications:1. Connect to the JNDI naming service.2. Look up for the connection factory and the source

of the message.3. Create a TopicConnection object.4. Create a TopicSession object.5. Create a TopicSubscriber (or queue receiver) to

receive a message.6. Subscribe (or receive) a message.7. Write code to process the message contents.

Receiving MessagesThe slide indicates the sequence of steps involved in receiving a message. The following are the code lines for each step:

1. Context ctx = new InitialContext();2. TopicConnectionFactory tcf = (TopicConnectionFactory)

ctx.lookup("...");Topic t = (Topic) ctx.lookup("...");

3. TopicConnection tc = tcf.createTopicConnection();4. TopicSession tsess = tc.createTopicSession(

false, Session.AUTO_ACKNOWLEDGE);5. TopicSubscriber tsub = tsess.createSubscriber(t);6. TextListener tl = new TextListener();

// TextListener implements MessageListenertsub.setMessageListener(tl);

7. Write the code to process the message contents in the onMessage() method of the TextListener class.



Asynchronous Message Delivery

• In an asynchronous messaging model, the consumer implements a MessageListenerinterface.

• The MessageListener interface declares an onMessage() method and notifies the consumer of the arrival of messages.

• MDBs are J2EE implementations for message listeners.

• A sender is not notified when the MDB processes the message.

Asynchronous Message Delivery The publish-and-subscribe or point-to-point communication models (discussed earlier in this lesson) can deliver the messages either synchronously or asynchronously. In a synchronous message delivery model, the consumer registers for a publisher (topic or queue) of interest and waits to receive a message from the message server. Therefore, the publisher is blocked until the consumer receives the message, the connection is timed out, or the consumer closes the connection. In an asynchronous message delivery model, a consumer registers for a publisher but may not wait for a message from the message server. The consumer implements a MessageListener interface. This interface defines an onMessage() method, which takes the incoming message from a publisher as a parameter and processes the message. The message server invokes this callback method when a message arrives from the publisher with which the consumer is registered. The message server informs the consumer of the arrival of the message.The asynchronous message delivery model is used by an MDB in a J2EE environment. A message-driven bean is a type of message listener object. When the onMessage() method of the MDB is invoked asynchronously, a sender is not automatically notified that the message has been processed. However, the MDB can send an acknowledgement message to a JMS Destination if the sender is designed to receive it.



Message-Driven Beans

MDBs:• Are programmed for receiving and processing

asynchronous messages through the JMS Destination

• Are stateless, server-side, transaction-aware components

• Are not accessible directly by any client • Do not contain home and component interfaces • Are triggered by a container when a message

arrives• Implement the javax.ejb.MessageDrivenBean

and javax.jms.MessageListener interfaces

Message-Driven BeansYou have learned that any Java application can be a consumer for the messages that arrive from the JMS publishers. Web applications are accessible through HTTP, and session or entity EJBs are accessible through RMI/IIOP. If a Web application or a session bean contains a method that listens for a message from a topic (or queue), the method looks up the connection factory and creates a connection, a session, and a subscriber. The method then waits to receive the message from the publisher. If there are no messages to be received, then the methods thread is blocked and the client has to wait until the message is received, and the wait may never end. Therefore, it is not good practice to block a thread while listening for JMS messages in a Web application, or a session or an entity EJB. A solution to avoid infinite waiting in the message listener is to call the receive()message method with a timeout, or to implement the receiveNoWait() method. The EJB 2.0 specification defines the MDB as a new EJB type designed to receive and process messages delivered asynchronously through the JMS architecture. MDBs are stateless. They reside in the server and can participate in transactions. MDBs are invoked through JMS and not RMI/IIOP, and they are never directly accessed from any client application. Therefore, MDBs do not contain home and remote interfaces. They are triggered by the container when a message is received at its destination.



MDB Architecture

OC4J

MDB

JMS resourceprovider

Queue/Topic

Client

MDB ArchitectureThe diagram in the slide shows an overview of MDBs with the OC4J JMS resource provider. MDBs can use OC4J JMS or Oracle JMS as resource providers.To configure OC4J JMS as a resource provider, specify the following in the jms.xml file:• <queue>: The JNDI location of the queue• <topic>: The provider-specific name and location for the topic• <queue-connection-factory>: The JNDI path for the connection factory• <topic-connection-factory>: The JNDI path for the topic connection

factory• <xa-queue-connection-factory>: The provider name and location for the

XA queue• <xa-topic-connection-factory>: The provider name and location for the

XA topic connection factory• <log>: The file name or e-mail address to send log messages for the OC4J queue

The MDB is declaratively associated with the OC4J JMS provider destination in the J2EE and OC4J deployment descriptors. A JMS session is established to receive messages from the destination in the onMessage() method of the MDB.



Associating JMS Resources with an MDB

Use the J2EE and OC4J deployment descriptors to specify the JMS resources associated with an MDB.• ejb-jar.xml:

• orion-ejb-jar.xml:<enterprise-beans> <message-driven-deployment max-instances="-1" name="MessageProcessor" connection-factory-location="jms/QueueConnectionFactory" destination-location="jms/demoQueue" min-instances="0"/> </enterprise-beans>

<message-driven> ...<ejb-name>MessageProcessor</ejb-name> ... <message-driven-destination> <destination-type>javax.jms.Queue</destination-type>

</message-driven-destination> </message-driven>

Associating JMS Resources with an MDBThe JMS resource type is specified in the J2EE deployment descriptor (ejb-jar.xml). The <message-driven-destination> child element of the <message-driven>element contains a <destination-type> element whose value can be either javax.jms.Queue or javax.jms.Topic.The <destination-type> value chosen must be consistent with the JMS element type, such as <queue> or <topic> in jms.xml, whose JNDI location name is used as the value for the MDB’s destination-location attribute in the orion-ejb-jar.xml file.Setting the actual resources used by the MDB is done in the OC4J-specific deployment descriptor, orion-ejb-jar.xml. The two JMS resources that must be specified are:

• A location for a topic or queue connection factory• A location for a topic or queue destination

These resources are set in the connection-factory-location and destination-location attributes of the bean’s <message-driven-deployment> element, respectively.



State Diagram of an MDB

Does not exist

Method-ready pool

Container invokes Class.newInstance,

setMessageDrivenContext(context)and

ejbCreate()

Container invokesejbRemove(…)

Container invokes onMessage()

State Diagram of an MDBThe state diagram of an MDB is identical to that of a stateless session bean. The container invokes the newInstance() method on the bean class to create a new instance. Then the container invokes the setMessageDrivenContext(sessCtx)and ejbCreate() methods on the bean instance. A bean instance is ready in the method-ready pool. When a client publishes a message, the container assigns one of the bean instances from the pool to the consumer and invokes the onMessage() method on the bean instance. This method performs the logic to process received messages. The life of an MDB ends when the container invokes the ejbRemove() method on the bean instance. The container removes a bean instance from the available pool when the instance is no longer required.


State Diagram of an MDB (continued)Because MDBs do not maintain a conversational state, a pool of instances can be created by the container so that each MDB instance can receive one message at a time. Therefore, the container can use additional MDB instances in the pool to receive and process other messages concurrently.One MDB can listen to more than one publisher. But an MDB is specific to one topic or queue from which it receives messages. These details are specified in the deployment descriptor of the bean.The container takes care of the environment settings such as transactions, security, concurrency, message acknowledgement, and so on. MDBs implement two interfaces: javax.ejb.MessageDrivenBean and javax.jms.MessageListener. Why does it implement two interfaces? The MessageDrivenBean interface is similar to the SessionBean and EntityBeaninterfaces of session and entity beans. The MessageListener interface is specific to JMS. Currently, MDBs can listen only to JMS messages. The MessageListenerinterface contains an onMessage() method that is specific to JMS. This method processes the messages that it receives.



Developing MDBs

1. Configure Oracle Application Server 10gContainers for J2EE (OC4J) with the JMS provider details.

2. Implement the bean class.3. Configure deployment descriptors:

a. Destination type for the bean in ejb-jar.xmlb. Connection factory and destination JNDI locations

in orion-ejb-jar.xml4. Create the EJB JAR file that contains the bean and

the deployment descriptors.5. Create the .ear file and deploy the bean.

Developing MDBsThe slide lists the sequence of steps that are involved in creating an MDB. To configure OC4J with the JMS provider details, configure the jms.xml file with the destination object information.Implement the bean class for an MDB, where you define how the message received by the bean should be processed.Configure the deployment descriptors for the JMS Destination:

• Specify the destination type used for the MDB in the EJB deployment descriptor (ejb-jar.xml).

• Specify the details of the destination used for the MDB in the OC4J-specific deployment descriptor (orion-ejb-jar.xml). Some of the details about destination are located in the application.xml configuration file.

Package the message-driven bean with its deployment descriptor and other supporting files. Create an Enterprise Archive file and deploy the bean to the OC4J instance. These steps are discussed in detail in the following pages.



Interfaces to Be Implemented for MDBs

• MessageDrivenBean interface:

• MessageListener interface:

package javax.ejb;public interface MessageDrivenBean extends

javax.ejb.EnterpriseBean{

public void setMessageDrivenContext(MessageDrivenContext context) throws EJBException;

public void ejbRemove() throws EJBException;

package javax.jms;public interface MessageListener {public void onMessage(Message message);

}

Interfaces to Be Implemented for MDBs The onMessage() method in the MessageListener interface is invoked by the container each time its subscriber’s topic receives a message. This makes the MDB a subscriber that can receive messages asynchronously from a queue or topic.Messages are processed inside the onMessage() method.



Implementing an MDB Class

The MessageLogger MDB example:package com.evermind.logger;import javax.ejb.*;import javax.jms.*;…public class MessageLogger

implements MessageDrivenBean, MessageListener {private MessageDrivenContext messageContext;public void ejbCreate() { }public void ejbRemove() { } public void setMessageDrivenContext(

MessageDrivenContext context) {this.messageContext = context;

}

Implementing an MDB Class In addition to the MDB class implementing the MessageDrivenBean and MessageListener interfaces, the bean class should define the ejbCreate() method. The ejbCreate() and ejbRemove() methods have the same functionality as in the session and entity EJBs. MDBs do not maintain state and, therefore, the ejbCreate()method does not take parameters. The resources that are needed by the MDB, such as a database connection, can be obtained in the the ejbCreate() method and closed and released in the ejbRemove() method when the bean instance is removed.The sample MDB, called MessageLogger, is triggered by the bean container when a message is published at the destination of the MDB (a topic in this example). The bean then prints the received message.The MessageLogger MDB shown in the slide implements the two required interfaces. Note that the javax.ejb package and the javax.jms package are imported for an MDB. No implementation is required for the ejbCreate() and ejbRemove() methods of an MDB. The setMessageDrivenContext() method is invoked by the container at the beginning of the bean’s life cycle. The context of the bean instance can be stored in this method, which can be reused every time the bean processes a message.



Receiving Messages in an MDB Class

The onMessage() method processes the received message.public void onMessage(Message msg){TextMessage msgText=null;try {msgText = (TextMessage) msg;String txt = (msgText).getText();System.out.println("Message received=" + txt);

} catch (Exception e) {throw new RuntimeException("onMessage error");

}}

Receiving an OC4J JMS Message in an MDB Class The onMessage() method is invoked by the container when a message is received at the destination of the MDB. The onMessage() method in the example receives a message that was created as a JMS ByteMessage. The message is then converted into printable text and printed.In the example in the slide, a message is received from a JMS topic, but it could also be from a JMS queue depending on how the deployment descriptor resources are mapped to the OC4J JMS resources.



Creating the Deployment Descriptor

MDB-related elements in the ejb-jar.xml file:<message-driven>

<ejb-name>...</ejb-name><ejb-class>...</ejb-class>

<transaction-type>...</transaction-type><message-selector>...</message-selector><acknowledge-mode>...</acknowledge-mode><message-driven-destination>

<destination-type>...</destination-type> </message-driven-destination><ejb-ref> ... </ejb-ref>

<security-identity> ... </ security-identity><resource-ref> ... </resource-ref>

</message-driven>

Creating the Deployment DescriptorThe general components associated with an MDB are listed in the slide. The <message-driven> element defines the following information in the deployment descriptor ejb-jar.xml:

• MDB name in the <ejb-name> element• MDB class in the <ejb-class> element• JNDI reference• JMS Destination type (queue or topic)• Transaction type of the MDB in the <transaction-type> element

These details are listed in the <enterprise-beans> element of the deployment descriptor.Note: There are no component interfaces defined for an MDB. The <message-selector> element indicates the message selection criteria for an MDB. Message selectors are conditional expressions based on the message header fields and properties of a message. Using a message selector, a consumer can filter the messages that it wants to receive from a message destination.


Creating the Deployment Descriptor (continued)Message selectors are based on SQL92 conditional expressions that can be used in the WHERE clause of a SQL statement. For example, the conditional expression for a message selector can be JMSPriority > 1, which filters only the messages with a priority equal to one. The following example for a message selector filters messages where order_status is pending for customer 123:<message-selector>

<![CDATA[

order_status = 'PENDING' AND customer_id = 123]]>

</message-selector>

The element <acknowledge-mode> is used by the container to acknowledge the receipt of the message from the destination. Without acknowledgement, the message broker tries to redeliver the message until it receives an acknowledgement. When an MDB involves transactions, the acknowledgement in the middle of a transaction is ignored to maintain the atomic, consistent, isolated, and durable (ACID) properties of a transaction. The receipt is acknowledged only when the transaction is complete. The element can take the values Auto-acknowledge or Dups-ok-acknowledge. When the value is set to Auto-acknowledge, the container sends an acknowledgement immediately after receiving the message. When the value is set to Dups-ok-acknowledge, the container can acknowledge the receipt any time after receiving the message. In the latter case, the message broker can send a message more than once to a consumer, creating duplicate messages.The <message-driven-destination> element indicates the type of destination from which the MDB receives a message. The possible values for the <destination-type> element are javax.jms.Topic and javax.jms.Queue. If the destination is Topic, then the durability of the subscription should be indicated in the <subscription-durability> element in the <message-driven-destination> element. If a subscription is specified to be nondurable, then the consumer is not able to receive messages that were delivered when the consumer was disconnected from the server. If a subscription is specified to be Durable, then the JMS provider delivers a message that could not reach a consumer (for example, because the consumer was not connected to the server when the message was delivered), when the consumer reestablishes its connection to the server. Similar to the session and entity beans, the MDB can specify the references to other EJBs, resources, and security identities.



ejb-jar.xml: Example

...<enterprise-beans><message-driven> <ejb-name>MessageLogger</ejb-name><ejb-class>btier.impl.MessageLogger</ejb-class><acknowledge-mode>Auto-acknowledge </acknowledge-mode><message-driven-destination> <destination-type> javax.jms.Queue </destination-type><subscription-durability>Durable </subscription-durability>

</message-driven-destination></message-driven>...

ejb-jar.xml: ExampleThe slide shows the <message-driven> element of the ejb-jar.xml file for the sample MDB. The MDB specifies its destination type as Topic and a durable subscription for the messages. The following code shows the complete deployment descriptor:<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN' 'http://java.sun.com/dtd/ejb-jar_2_0.dtd'>

<ejb-jar><enterprise-beans><message-driven>

<ejb-name>MessageLogger</ejb-name>

<ejb-class>btier.impl.MessageLogger</ejb-class>

<acknowledge-mode>Auto-acknowledge</acknowledge-mode>

<message-driven-destination>

<destination-type>javax.jms.Queue</destination-type>

<subscription-durability>Durable</subscription-durability>

</message-driven-destination>

</message-driven></enterprise-beans></ejb-jar>



Mapping in OC4J-Specific Deployment Descriptor

In the orion-ejb-jar.xml file, associate a JMS Destination with the MDB in the <message-driven-deployment> element by using the following attributes:• Name: MDB name as defined in the <ejb-name>• connection-factory-location: JMS

Destination Connection Factory• destination-location: JMS Destination• subscription-name: Subscription name

(required only if the JMS Destination is a topic)

Mapping in OC4J-Specific Deployment DescriptorAfter you have configured the MDB and the JMS Destination type, you must inform the container which JMS Destination to associate with the MDB.You could have several topics and queues defined in the jms.xml file for OC4J JMS. To identify the destination that is to be associated with the MDB, you map the connection factory and destination names to their JNDI locations through the <message-driven-deployment> element in the orion-ejb-jar.xml file. These details are dependent on the JMS provider. If you use a topic as a destination for your MDB, then you also specify the subscriber name of the topic from which your MDB receives a message. This is required because a topic can have more than one subscriber.For information about defining these JMS Destination types in jms.xml, see the Oracle Application Server Containers for J2EE Services Guide.



orion-ejb-jar.xml: Example

<enterprise-beans><message-driven-deployment name="MessageLogger"connection-factory-location=

"jms/QueueConnectionFactory"> destination-location=

"jms/demoQueue"</message-driven-deployment> ...

</enterprise-beans>

orion-ejb-jar.xml: Example The code in the slide is the orion-ejb-jar.xml deployment descriptor for the MessageLogger example. It maps a JMS Queue to the MessageLogger MDB, providing information in the following attributes:

• The name of the MDB is MessageLogger as defined in the ejb-jar.xml file. • The connection-factory-location attribute specifies the name of the OC4J

JMS Destination connection factory location. • The destination-location attribute sets the OC4J JMS Destination location.

After these attributes are specified in the <message-driven-deployment> element, the container associates the MDB with the OC4J JMS Destination, based on how the attribute values are mapped to the JMS resources.



Creating an MDB with JDeveloper

1

2

3

Creating an MDB with JDeveloperThe process of creating an MDB with JDeveloper is the same as creating any other EJB. In the EJB module editor, select the Business Tier category, and then select Message-Driven Bean from the Enterprise JavaBeans section. Specify the name of the MDB to be created. Note: No interfaces are created for this bean.The slide also shows the MDB node and the code associated with the bean. Note that only a bean class is created for an MDB, and the bean class contains an onMessage() method.




ejb-jar.xml

Creating an MDB with JDeveloper (continued)In the EJB module editor, expand the MDB node and click Destination. On the right of the frame, select a destination type for the MDB. The destination type can be either a javax.jms.Queue type or a javax.jms.Topic type. In this example, the destination type is a topic. For a topic, you also have to select whether the subscription is durable or nondurable. After you make these selections, JDeveloper adds the necessary code in the ejb-jar.xml file as shown in the slide.




Map the destination details in orion-ejb-jar.xml.

orion-ejb-jar.xml

Creating an MDB with JDeveloper (continued)Map the destination details to JNDI locations in the orion-ejb-jar.xml file.



Testing the MDB

1. Deploy the session and the MDBs.2. Create a client to invoke the message-sending

functionality.3. Run the client application to send the message to

the JMS Destination.4. Observe the output in the run-time environment.

Testing the MDBThe JDeveloper-embedded OC4J container cannot be used to run the MDB. Therefore, you must create a deployment profile for the MDB and deploy it to a stand-alone OC4J container or an OC4J instance in Oracle Application Server 10g.After deploying the MDB, you must create a client application that has the functionality to send a message to the required JMS Destination. The client application could be a stand-alone GUI, command line, Web, or EJB implementation. When you execute a client, you can observe the operation of the message delivery process, depending on the run-time environment of the MDB and depending on whether the developer of the MDB has provided visual confirmation of message processing.The example in the slide shows the output of an MDB that is running in a stand-alone OC4J container started in a command-line window.



Summary

In this lesson, you should have learned how to:• Describe the different types of MOM:

– Point-to-point– Publish-and-subcribe (pub/sub)

• Create an MDB• Compare a stateless session EJB and an MDB• Describe JMS• Configure a JMS resource provider in the OC4J

jms.xml file

SummaryIn this lesson, you should have learned the concepts of JMS. You should have also learned how to create and access MDBs.




This practice covers the following topics:• Creating a simple MDB to accept a message from

an OC4J JMS queue, and writing the message to a log table by using an entity bean

• Configuring the message-bean deployment descriptor to use an OC4J JMS resource

• Writing and configuring a JavaServer Pages (JSP) application to send a message from an HTML form to the OC4J JMS queue

Practice 16-1: OverviewIn this practice, you create an MDB to read a message from an OC4J JMS queue. The MDB uses a supplied entity bean to write the message to a record in a log table. You are required to modify the message-bean deployment descriptor to associate the MDB with the OC4J JMS connection factory. You then modify an existing JSP that is invoked by an HTML form. The JSP accepts an employee id, a job id, and a text message that is used to create a message that is sent to the OC4J JMS queue.


Practice 16-1In this practice, you create a simple message-driven bean to receive messages from an OC4J JMS queue, and modify a JSP to send messages to the EJB. Open the practice16.jwsworkspace in the practice16 directory. The workspace contains the two projects webtier and businesstier, along with their respective solution projects webtiersoln and businesstiersoln.

1. Create the log message table used by the Logmessages entity to store messages that are sent to the MDB that you create. Use SQL*Plus to execute logmessages.sql from the directory: E:\jdev9051\jdev\mywork\practice16

2. Now modify some OC4J configuration files to use OC4J JMS.a. Create a new queue and data source reference. Open a browser and navigate to

http://localhost:1810. Enter the username ias_admin and the password welcome1. Click on the home instance page.

b. Click the Administration tab and the Advanced Properties link. Click the jms.xml link to add a queue and queue connection factory.

c. Create a new queue named "jms/Queue/Queue1" with a location of "jms/Queue/Queue1". Provide the queue connection factory location as "jms/Queue/QCF". It is important that you type these entries and do not copy and paste from another location. Click Apply and then click OK.

d. Next create a new data source. From the home instance page, click the Data Sources link. Click Create and enter these details:

Name: LogDSDescription: logData Source Class:

com.evermind.sql.DriverManagerDataSourceJDBC URL: The URL provided to you by your instructorJDBC Driver: oracle.jdbc.driver.OracleDriverIn Datasource Username:Username: oraxx (as provided to you by your

instructor)Use a cleartext password of oracleIn JNDI Locations: Location: jdbc/LogCoreDSTransactional location: jdbc/xa/LogXADSEJB location: jdbc/LogDSLeave all other fields blank or set to the default.

e. Click Create and restart the server when prompted.3. Create a simple MDB to accept a message from an OC4J JMS queue, and store the

message text as a record in a log table by using the Logmessages entity bean provided.

a. In the businesstier project, create a new Enterprise JavaBean of the MDB type. Define the bean name as MessageLogger.


Practice 16-1 (continued)b. In the onMessage() method of the bean, process only the TextMessage

objects from the queue, and ignore other message type objects. Get the message string by using the getText() method of the TextMessage object, and use the getLongProperty() method of the TextMessage object to get the value of a property named msgid in a Long object variable.Note: Be sure to import javax.jms.TextMessage.

4. Associate the MDB with the OC4J JMS resource provider, the JMS queue from which it receives messages, and the entity bean used to save the message to the log table.

a. Open the EJB Module Editor, expand the MessageLogger bean node, select the EJB Local References section, and click the Add button. Select Logmessages from the "Auto-create Reference to the EJB" drop-down menu.Note: This action adds a getLogmessagesLocalHome() method in the MessageLoggerBean class to access the entity bean's local home interface,and a <ejb-local-ref> element to the ejb-jar.xml file.

b. Select the Destination node and check "Specify Message Driven Destination". Set the Destination Type to javax.jms.Queue and the Subscription Durability to Durable. Click OK to close the window.

c. Copy the contents of the addLogMessage.txt file in the E:\jdev9051\jdev\mywork\practice16 directory into theMessageLoggerBean class. This code provides the method to save the textmessage in the database table by creating an instance of the Logmessagesentity bean.Note: Import the following packages: java.sql.Timestamp, java.util.Date, and javax.ejb.CreateException.

d. In the MessageLoggerBean onMessage() method, call theaddLogMessages() method as the last line of the try block. Supply the long msgid property value obtained from the message and the text message string as arguments.

e. Define the OC4J JMS resources used by the MDB, and map the logical JMS resource to the OC4J JMS resources. Right-click orion-ejb-jar.xml and select Properties. In the OC4J EJB Deployment Descriptor window, select the MessageLogger section under Enterprise JavaBeans. In the Connection Factory Location field, enter jms/Queue/QCF. In the Destination Location, enter jms/Queue/Queue1. These are OC4J JMS queue connection factories and queue resources you defined in step 2b.

5. Compile the files in the businesstier project and correct any syntax errors. Right-click ejb-jar.xml and select Create EJB JAR Deployment Profile from the menu, and enter MessageLoggerEJB.deploy as the filename. Click OK, then click OK again to close the window.


Practice 16-1 (continued) 6. Expand the webtier project and open the SendMessage.jsp in the code editor.

You now add the code to send a message to the OC4J JMS queue.a. SendMessage.jsp is invoked from an HTML form action that is generated

by the LoginServlet. In SendMessage.jsp, you should construct the string message to contain the request parameter values (obtained from the form fields) for empid, jobid, and msg, concatenated into a space-separated list.

b. Write code to create a QueueConnectionFactory object by using the JNDI name of jms/Queue/QCF, and a Queue object using the JNDI name of jms/Queue/Queue1. Create a QueueConnection, QueueSessionand TextMessage object, setting the text of the TextMessage object to the string formatted in the previous step. Prior to sending the message, use the message object setLongProperty() method to set a property named msgid to the value of msgId variable, which holds a unique message ID obtained from an Oracle sequence. Finally, write the code to send the TextMessage to the queue.

c. Change the username and password in the doPost() method of LoginServlet.java and in the database tags in SendMessage.jsp to utilize your username and password.

7. Create the logical JMS resources used in the JSP in the J2EE deployment descriptor.a. Right-click web.xml and select Properties. Select the Resource References

section to create logical resources by clicking the Add button. Create a reference with a name field jms/Queue/QCF and a Resource Typefield javax.jms.QueueConnectionFactory.

b. Click the Add button again to create a second reference with a jms/Queue/Queue1 name field and a javax.jms.Queue Resource Type field.

8. Compile the files in the webtier project and correct any syntax errors. Right-click web.xml and select Create WAR Deployment Profile, and then enter the file name LogMessageApp.deploy. Click OK. In the Profile Dependencies section, select the box next to the MessageLoggerEJB.deploy entry. Then click the OK button to close the window.

9. Right-click LogMessageApp.deploy and deploy the application (including the dependent MessageLoggerEJB) to the OracleAS10g connection. Note that it could take several minutes to deploy the application.


Practice 16-1 (continued) 10. Run the Web application to test the logic by entering one of the following URLs in your

Web browser: http://localhost/logmessage/ or http://localhost/logmessage/loginservlet. Usernames and passwords are listed below. Hint: Use the Show Messages hypertext link in the application window to viewmessages written to the LOGMESSAGES table by the MDB.

Mavris203

de Haan102

King100


Integrating J2EE Components



Objectives

After completing this lesson, you should be able to do the following:• Create JavaServer Pages (JSP) clients for EJBs • Use Enterprise JavaBeans (EJB) tags in JSPs• Modify the configuration files in OracleAS 10g

Containers for J2EE (OC4J)



Overview

JSP

HttpServletRequest

Web tier EJB tier

Controllerservlet

Employees JSP

Employees EJB

To EIS

HttpServletResponse

OverviewThe slide shows a sample application that adheres to the Model-View-Controller (MVC) framework. In this application, a JSP accesses EJBs through a Controller servlet, which forwards the user’s request to the appropriate JSP. The Employees JSP acts as a client to the EJB. This lesson teaches you how to access EJBs from JSP, and how to deploy an application such as the one shown in the slide.



Creating Remote Clients for EJBs

To create a remote JSP client for an Enterprise JavaBean, perform the following steps :1. Import the EJB home interface.2. Override the jspInit() method.

– Use the lookup() method to create a reference to the EJB.

– Create the EJB remote object.3. Retrieve the necessary parameters from the

request object and pass the parameters to the EJB method.

4. Define a reference to the EJB in the web.xml file.

Creating Remote Clients for EJBsTo create a remote client by using a JSP, first import the EJB Home interface. Use the jspInit() method to retrieve a reference to the EJB by using the lookup() method of the InitialContext object. Request object parameters can then be retrieved as usual in a JSP (by using the request.getParameter() method), and passed to the EJB methods. Lastly, a reference to the EJB is created in the web.xml file so that the JSP client can find the required interfaces.



Importing the EJB Home Interface

Use the page directive to import the naming package and the home interface for the EJB:<%@ page import="mypackage.Employees, mypackage.EmployeesHome, javax.ejb.*, javax.naming.*, javax.rmi.PortableRemoteObject, java.rmi.RemoteException" %>

Importing the EJB Home InterfaceBy using a page directive in the JSP, import the home and remote interfaces for the EJB, as well as the PortableRemoteObject, RemoteException, and the javax.namingpackage for the InitialContext lookup. Import these packages as usual for a Java file in a servlet:

import mypackage.Employees.*;import java.io.*;import javax.servlet.*;import javax.servlet.http.*;import javax.naming.*;public class EJBClientServlet extends HttpServlet {…}



Create a Reference to the EJB

To create an EJB reference, use the lookup method. Override the jspInit() method as follows:<%! Employees employees = null;public void jspInit() {try { InitialContext ic = new InitialContext();EmployeesHome employeesHome = (EmployeesHome)

PortableRemoteObject.narrow(ic.lookup("java:comp/env/Employees"), EmployeesHome.class);

employees = employeesHome.create(); } catch (RemoteException ex) {

ex.printStackTrace(); }}%>

Create a Reference to the EJBBecause locating the home interface and creating the EJB are performed only once, they should be performed in the jspInit() method within a declaration. In a servlet, this can be performed in the init() method.



Passing Arguments to the EJB Method

Calling an EJB method from a JSP expression evaluates the return value of the EJB method and displays it, as follows:<html><body><h1>Insert an Employee Number:</h1><form method="get"><p><input type="text" name="empno"><p><input type="Submit" value="Submit"></form><% String empno = request.getParameter("empno");

if (empno != null && empno.length() >0) { int i = Integer.parseInt(empno);%><%= employees.getDetails(i) %>

<% } %></body></html>

Passing Arguments to the EJB MethodUse expressions to evaluate the return value of the EJB business method at run time. In a servlet, the code seen above would be performed by wrapping the return value of getDetails() in an out.println() method.



Creating an EJB Reference

To obtain an EJB reference for the Web tier components, create an <ejb-ref> element for the EJB in the web.xml file:

Creating an EJB ReferenceTo create an EJB reference in the web.xml file, right-click the file in JDeveloper and select Settings. After clicking the Add button from the EJB references category, you can give the details of the reference as shown in the screenshot below:



Creating Local Clients for EJBs

Creating JSP clients for local EJBs is similar to creating remote clients, with the following exceptions:• The EJB object does not have to be cast to a

PortableRemoteObject.• Because the create() method does not throw a

RemoteException exception, this does not have to be caught in the client.

• Instead of <ejb-ref>, an <ejb-local-ref>element is created in the client web.xml file.

Creating Local Clients for EJBsThere are three differences between using remote EJBs and local EJBs. An example of a web.xml file that references a local EJB is as follows:

<ejb-local-ref><description>Reference to Local Bean</description><ejb-ref-name>Employees</ejb-ref-name><ejb-ref-type>Session</ejb-ref-type><local-home>package1.EmployeesLocalHome</local-home><local>package1.EmployeesLocal</local>

</ejb-local-ref>



ejb-local-ref Element

Right-click web.xml to create an EJB local reference.

ejb-local-ref ElementInstead of creating an ejb-ref element for remote EJBs, create an ejb-local-refelement in the web.xml file by right-clicking it. Select EJB Local References, and then add a reference as shown in the slide.



EJB Tags

Oracle Application Server 10g provides a tag library that contains custom tags for referencing EJBs in JSPs:

EJB Tag Purpose

useHome Looks up the home interface for the EJB and creates an instance of it

useBean Instantiates the EJB

createBean Nests an EJB createBean tag within the useBean tag to create the EJB instance

iterate Iterates through a collection of EJB instances

EJB TagsYou can retrieve references to EJBs by using the EJB tags that are provided in the OJSP (OC4J JSP) library. Use the useHome bean to look up a home interface for the EJB. The useBean tag instantiates the EJB. You can specify either the value attribute or a nested createBean tag to create the EJB instance. The iterate tag iterates through EJB instances. This is commonly used for entity beans, because standard finder methods for entity beans return collections.



useHome Tag

The useHome tag has no body. The attributes are:• id (required)• type (required)• location (required)

<EJB:useHome id="empHome" type="mypackage.EmployeesHome" location="java:comp/env/ejb/Employees" local="false" />

useHome TagDefine three attributes in the useHome tag. First, specify the id, which is a name for the home interface instance. Next, specify the name of the home interface in the type attribute. Lastly, provide the Java Naming and Directory Interface (JNDI) location that is used to look up the home interface of the EJB. This should correspond to your <ejb-ref> element entry in the web.xml file. The local attribute should be false when the type class name refers to the remote home interface of the bean, and true when using the Local Home interface.



useBean Tag

The attributes of the useBean tag include:• id (required)• type (required)• value• scope

<EJB:useBean id="bean" type="mypackage.EmployeesBean" scope="session" />

useBean TagFirst, specify an instance name for the EJB in the id attribute. Next, specify the class name of the EJB in the type attribute. You can use the value attribute or a nested createBean tag to create the instance, as shown below. Lastly, specify the scope of the instance. This can be page, session, request, or application, similar to specifying the scope in JSPs for JavaBeans.

<EJB:useBean id="bean" type="mypackage.EmployeesBean" scope="session"> <EJB:createBean instance="<%=empHome.create()%>" />

</EJB:useBean>



createBean Tag

The createBean tag contains only one required attribute named instance.

<EJB:useBean id="bean" type="mypackage.EmployeesBean" scope="session"> <EJB:createBean instance="<%=EmployeesHome.create()%>" /> </EJB:useBean>

createBean Taginstance is a required attribute of createBean, which returns the EJBObjectinstance. In the example given in the slide, the create() method of the EJB home interface creates the instance.



iterate Tag

The following are the attributes of the iterate tag: • id (required)• type (required)• collection (required)• max

<EJB:iterate id="empdetails" type="mypackage.Employees" collection="<%=bean.getDetails(pk)%>" max="100"> <jsp:getProperty name="empdetails" property="id" /> </EJB:iterate>



Using the EJB Tags

To use the EJB tags, perform the following steps:1. Add the Oracle9iAS library to your project in

JDeveloper.a. Double-click the project and select libraries.b. Make sure that “Oracle9iAS” is included in your

project.2. Use the OJSP EJB Library provided in the

component palette to add the necessary tags to your JSP file. (This adds the bean as well as the taglib directive to the JSP.)

Using the EJB TagsWhen you include the Oracle9iAS library in your project in JDeveloper, you can easily incorporate the EJB tags in your JSP. The component palette contains a list of different tags to be used. Select the “OJSP EJB” category in the component palette. You can then add any of the tags discussed previously by placing your cursor in the JSP and selecting the tag. Adding a tag in this way also adds the tag library directive to your JSP, as shown below:

<%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/ejbtaglib.tld" prefix="EJB" %>

Note that although you can specify any prefix value, “EJB” is conventionally used.



Deploying an Application: Web Tier

To deploy the Web tier components of a Java 2, Enterprise Edition (J2EE) application, perform the following steps:1. Make sure that the ejb-ref or ejb-local-ref

elements exist in the web.xml file.2. Create a WAR deployment profile (.deploy) in

JDeveloper.3. Right-click the .deploy file and select either of

the following:– Deploy to WAR file– Deploy to OracleAS10g (where OracleAS10g is the

name of your application server connection)

Deploying an Application: Web TierAfter you have added the EJB client access to a JSP application and have ensured that the proper ejb-ref or ejb-local-ref elements exist in the web.xml file, you can deploy the application. Create a WAR deployment profile in JDeveloper, and right-click the file to deploy it. You can either deploy the application directly to Oracle Application Server 10g, or create a Web Archive (WAR) file.



Deploying an Application: EJB Tier

1. Make sure that the ejb-jar.xml file contains unique mappings for each EJB in the application.

2. Create a JAR deployment profile (.deploy) in JDeveloper.

3. Right-click the .deploy file and select either of the following:– Deploy to JAR file– Deploy to OracleAS10g

Deploying an Application: EJB TierIn the same way as you deployed a WAR file, create a deployment profile for the EJB components. When this deployment profile is deployed to a Java Archive (JAR) file, it can then be included in an Enterprise Archive (EAR) file with the WAR file for the application. This is shown in the next slide.



Deploying an Application: EAR File

1. Create an EAR file in JDeveloper.2. Specify the EJB JAR and WAR files that are to be

included in this EAR file.3. Right-click the .deploy file and select either of

the following:– Deploy to EAR file– Deploy to OracleAS10g

Deploying an Application: EAR FileAfter you have deployed an EJB JAR file and a WAR file, create an EAR file for the application. Specify the JAR and WAR files that are to be included in this deployment profile, as shown below. Right-click the .deploy file for the EAR deployment profile to deploy it either directly to Oracle Application Server 10g or to an EAR file for deployment via command line or Oracle Enterprise Manager Application Server Control.



Deploying from Oracle Enterprise Manager

From the Enterprise Manager home page, click Home, then Application, and then select Deploy EAR file:

Deploying from Oracle Enterprise ManagerSpecify the EAR file that you generated from the .deploy file and the application details as shown below:



Summary

In this lesson, you should have learned how to:• Create JSP clients for EJBs • Modify deployment descriptors for looking up an

EJB client • Deploy a J2EE application to Oracle Application

Server 10g



Practice 17-1 and 17-2: Overview

These practices cover the following topics:• Creating JSP clients that access EJBs• Deploying a Web application to Oracle Application

Server 10g


Practice 17-1The purpose of this practice is to create JSP clients for the EJBs that you have written in previous practices. Within practice17ske.jws, there are two projects, businesstier.jpr and webtier.jpr (the solution files are contained in practice17soln.jws). businesstier.jpr contains the Employee session EJB that you developed in practice 12, as well as the UpdateEmployee entity EJB that you created in practice 14. The webtier project contains the LoginServlet that you created in practice 5. In this practice, you put together all the knowledge to create a complete J2EE application.

1. Modify LoginServlet to test a user who logs in. In this practice, because company employees are using the application, change the LoginServlet to verify the login for an employee, rather than for a customer.

a. In the init() method, change the data source lookup to jdbc/hrDS.b. In the doGet() method, change the heading for the human resources

application and change the form’s fields to accept the employee ID and employee name.

2. Modify the verifyCustomer() and getOrders() methods to verifyEmployee() and getRoles(). Only employees who have a valid login will be accepted, and only employees who have an administrator role will be allowed to insert new employees (who will be added later).

a. Change verifyCustomer() to verifyEmployee(), and return a jobidfrom this method. Pass in a connection, employee_id, and employee_name as arguments to this method. The jobid will be used to check for the administrator roles in the getRoles() method.

b. Change the statement to select the employee_id, last_name, and job_idfrom the EMPLOYEES table where the last_name is the employee_namethat is passed to this method, and where employee_id is the employee ID that is passed to this method.

c. In the while loop, set the value of jobid to the job_id from the query. Remove the code for checking the custid value.

d. Change getOrders() to getRoles(). This method will return a Boolean value, indicating whether the employee is an administrator. It will accept the connection and the jobid from the verifyEmployee() method.

e. Create a variable for this method, initialized to null, to store the value of the string that is returned from the query.

f. Change the prepareStatement() method (in the init() method) to select job_id from the JOBS table where job_id is equal to the argument passed to the method. In the getRoles() method, use the setString() method to pass in the argument.

g. In the while loop, set the value of the variable created in step e. to the jobid that is returned from the query.

h. If the value equals HR_REP, AD_PRES, or AD_VP, return true. Otherwise, return false.

3. Create a new method to forward the request to a JSP in the application.a. Name the method gotoPage(). It should accept an address (as string) and the

HttpServletRequest and HttpServletResponse objects, and then throw the ServletException and IOException exceptions.


Practice 17-1 (continued)b. Create a variable of type RequestDispatcher and use

getServletContext().getRequestDispatcher() to assign the value of the address passed to the method.

c. Forward the request and response by using the forward method of the RequestDispatcher variable.

4. Modify the doPost() method to include the new functionality.a. Modify the id and name variables to retrieve the value of the parameters from

the doGet() method’s form.b. Create a string variable initialized to “false” to store a “flag” if the employee

is an administrator.c. In the try/catch block, store the return value of verifyEmployee(conn,

id, name) in a string variable.d. If this variable is not null, then verify that the getRoles() method returns

true. e. If getRoles() returns true, then set the variable that you created in step b to

“true” and use the setAttribute() method of the request object to create an attribute named adminflag with a value of the variable.

f. Whether or not getRoles() returns true, the user will be able to see a list of employees. Set a request attribute to store the value of the id variable to an attribute named empid.

g. Call the gotoPage() method by passing in ViewEmployees.jsp as the address, and the request and response objects.

h. If the variable created in step c is null, the employee’s login is invalid.i. Eliminate the code in the method for viewing the orders, because this

functionality is no longer required.j. Compile LoginServlet.java.

5. Create an EJB reference for the Employee EJB that you created in practice 12.a. Right-click web.xml in the WEB-INF folder of the webtier project and

select Properties.b. Select EJB references and add a new reference.c. Supply the name as Employee, the home interface as

businesstier.EmployeeHome, the remote interface as businesstier.Employee, and make sure that the type is session. Click OK.

d. Open web.xml in the editor to view this reference. You can now access the EJB by using the java:comp/env/Employee reference.

6. Create a client for the Employee EJB.a. Navigate to EmployeeBean.java in the businesstier project. A

method called getEmployeesInDept() has been added to this EJB to retrieve a vector of the employees in a given department. Note that the EmployeeDetails class has been modified to retrieve the values of the id, fname, lname, email, hiredate, and jobid arguments.

b. Create a new JSP in the webtier project named ViewEmployees.c. Rename the title for the JSP.


Practice 17-1 (continued)d. Import the following:

businesstier.Employee, businesstier.EmployeeHome, javax.naming.*, javax.ejb.CreateException,

javax.rmi.PortableRemoteObject, java.rmi.RemoteException,

java.util.*, businesstier.EmployeeDetailse. In a declaration, create an instance variable to hold an object of Employee

type.f. Still in the declaration, override the jspInit() method. Use a try/catch

block to look up the Employee EJB by using the reference that you created in step 5.d. by catching the CreateException, NamingException, and RemoteException exceptions.Hint: Use page 6 of this lesson as an example.

g. Outside the declaration, create a variable to retrieve the value of the employee ID that is stored in the request object.

h. Retrieve the value of the employee ID that you set in step 4.f. by using request.getAttribute(). Assign it to an int variable. You must cast this String value to an Integer.

i. Initialize an object of EmployeeDetails type to null.j. Create a 3 row, 4 column HTML table and insert headers in the first row to

display the employee id, first name, last name, and e-mail.k. In the source code editor, add a scriptlet to create an Enumeration of the

getEmployeesInDept() method’s elements.l. While there are more elements in the enumeration, advance through the

EmployeeDetails object that you created in step d by using the nextElement() method. Cast the return to the object you created in step h.

m. Navigate to the second row of the HTML table and between <td> elements, retrieve the values of the id, first name, last name, and e-mail by using the methods from the EmployeeDetails object.

n. Close the while loop.o. Verify whether the employee is an administrator. Use

request.getAttribute() to retrieve the value of adminflag. If this attribute is not equal to null, check if the value is “true.” If the value is true, then create an href link in the third table row to AddEmployees.jsp. You create AddEmployees.jsp in the next step.

p. Compile the businesstier project and ViewEmployees.jsp.7. Create AddEmployees.jsp. This JSP allows an administrator to insert a new

employee by using the entity bean that you created in practice 14.a. Create AddEmployees.jsp in the webtier project. b. Rename the title for the JSP.c. This JSP provides a form for completing employee details and submits to itself.

Verify that the insert parameter is null. If it is null, then create a form as follows:

i. The action for the form returns the request to this JSP.


Practice 17-1 (continued)ii. Create an HTML table containing seven rows and two columns.iii. In the first column, create a text label to describe the data entered, such as

Enter an Employee Id:. The second column must be a text field, with the name attribute set to empid, fname, lname, email, hdate, and jobid. These text fields do not contain any values.

iv. Create the Insert button in the last row.v. After the last row, create a hidden value to provide the insert parameter

as “true.”Hint: Use the HTML tags in the component palette for easy table and form object creation.

d. If the insert parameter is not null, and if it is “true,” then the user has entered data into the form. Thus, you need to insert this data using the UpdateEmployees EJB. This time, use the OJSP EJB tag library to access the bean. Check for the “insert” parameter condition and retrieve the values of each of the text items from the form. You will need to use Integer.parseInt() to parse the empid value.

e. Create a reference to the EJB in the web.xml file as in step 5, this time providing businesstier.UpdateEmployeeHome as the home interface, and businesstier.UpdateEmployee as the remote interface. Give the reference a name and specify that this bean is an Entity bean.

f. In AddEmployees.jsp, place your cursor beneath the scriptlet that contains the retrieval of the form values, and select the OJSP EJB category from the component palette.

g. Use the UseHome tag to create a reference to the UpdateEmployees EJB. Supply an ID of entityhome, a type of businesstier.UpdateEmployeeHome, and the location as java:comp/env/<yourrefname>, where <yourrefname> is the reference name you provided in step e.

h. In a scriptlet, call the create() method of UpdateEmployee by using the entityhome reference. Pass in the values that are retrieved from the form submission.

i. Supply some text to notify the user that the employee has been added, and close out the condition.

8. Compile the businesstier and webtier projects and run LoginServlet to test. Employees who are administrators are listed below. Note that there is a database constraint that employee IDs and e-mail addresses must be unique.

Mavris203

de Haan102

Kochhar101

King100

Last NameEmployee ID


Practice 17-2In this practice, you deploy the application that you created in Oracle Application Server 10g.

1. Create an EJB JAR file for the businesstier project.a. Right-click businesstier and select New.b. From the “Deployment Profiles” category, select “EJB JAR File.”c. Accept the default deployment profile name.d. Specify the enterprise application name as hrejb.e. Right-click the deployment profile and select “Deploy to JAR file.”

2. Create a WAR file for the webtier project.a. Right-click webtier and select New.b. From the “Deployment Profiles” category, select “WAR File.”c. Accept the default deployment profile name and click OK.d. Specify the context root as /hrapp.e. Right-click the deployment profile and select “Deploy to WAR file.”

3. Create an EAR file for the application.a. Right-click webtier and select New.b. From the “Deployment Profiles” category, select “EAR File.”c. Accept the default deployment profile name and click OK.d. Name the application hr.e. In the Application Assembly category, include the deployment profiles that you

created in steps 1 and 2 and click OK.f. Right-click the deployment profile and select “Deploy to EAR file.”

4. Deploy the application by using Oracle Enterprise Manager.a. Navigate to http://localhost:1810 and supply the username as

ias_admin and the password as welcome1.b. Select home to open the OC4J home instance page.c. Click the Applications tab and click the Deploy EAR File button.d. Browse for the application1.ear file. By default, this will be in

practice17ske\webtier\deploy. Supply a name of practice17 for the application name and click Continue.

e. Verify whether the URL binding for this application is /hrapp, and click Next. This means that you can access the application by using this shortened name.

f. Enter jdbc/hrCoreDS for the JNDI location name and click Next. In practice 2, you have already mapped this data source in OC4J.

g. Click Next at the following page because there is no user security defined for this application.

h. Click Deploy to deploy the application.5. Test the application by accessing the following URL:

http://localhost/hrapp/loginservlet


Distributing Modular Applications: Introduction to Web Services



Objectives

After completing this lesson, you should be able to do the following:• Describe the Web services technology• Identify the standards used by Web services• Identify the benefits of Web services• Distinguish between remote procedure call (RPC)-

style and document-style Web services • Discuss the role of Simple Object Access Protocol

(SOAP), Web Services Description Language (WSDL), and Universal Description, Discovery, and Integration (UDDI) in Web services

ObjectivesThis lesson provides an overview of Web services. This lesson also discusses some of the “de facto” industry standards such as Simple Object Access Protocol (SOAP), Web Services Description Language (WSDL), and Universal Description, Discovery, and Integration (UDDI). In addition, you learn about the benefits of Web services.



What Is a Web Service?

External applications

HTML

XML

Webpresentation

Businesslogic

Webservice Databases

Application Server

HTTP client

What Is a Web Service?A Web service is a software component identified by a Uniform Resource Identifier (URI), whose interfaces and binding can be described by standard Extensible Markup Language (XML) vocabularies. Web service supports direct interactions with other software applications or components and is network accessible. With Web service, you can make your applications programmatically accessible to other applications over the Internet.Browser-based applications provide a Hypertext Markup Language (HTML) front end to a back-end application. The front-end application usually contains an HTML form in which the user enters the data and invokes the back-end application. These applications are valuable because they expose strategically important assets to the outside world. However, a disadvantage of this approach is that data must be entered into a browser screen to access the information. If multiple windows are open, then the user might provide incorrect data or enter the retrieved information into a different Web site, which might cause unwanted delays and errors. It is more efficient for information to be transferred automatically between applications.Web service enables programmatic access of information across the Internet. Unlike Web applications with an HTML form, a Web service can be accessed without a browser. When you consider the type of information or functionality that you might want to expose as a Web service, consider the functions that you currently provide via your Web sites and portals.



Web Service

A Web service is:• A software component whose technology is based

on a set of standards for building interoperable distributed applications

• A set of self-describing business functions• Service oriented• Component based

Web ServiceNeed for Web ServicesSeveral businesses today have become e-businesses. The greatest challenge for thesuccessful transformation is application-to-application communication. An enterprisesolution usually has multiple applications, each running on different hardware and sometimes implemented in different languages. There is often a need to communicate and exchange data between applications. To achieve this, developers spend time writing the plumbing application. Web service is a technology based on a set of standards that provides a solution for application-to-application communication and enterprisewide application integration.Standards for Interoperable Distributed ApplicationsEnterprise solutions are developed with a variety of languages such as C++, Java, Visual Basic (VB), and so on. A main requirement of such applications is the need to integrate and exchange data with other applications. By using Web services, clients and servers can communicate over standard Internet protocols regardless of the platform or the programming language. Developers can write their business functionality in any language and on any preferred platform. The applications that are developed must adhere to the standards so that they can be exposed and accessed as Web services.


Web Service (continued) Self-DescribingWeb services are discrete business processes. Web services describe their functionality, and the location (the application server to which the service is deployed) from where they can be accessed, so that applications can use them.Service OrientedWeb services are developed to offer some service over the Internet.For example: A currency converter can be a Web service. Clients who need the currency conversion in their applications can use the available service rather than coding the functionality themselves. Component BasedWeb services are an addition to the list of distributed computing models such as Common Object Request Broker Architecture (CORBA), Component Object Model (COM), and Distributed Component Object Model (DCOM). Web services are platform independent and language independent. But unlike these technologies, Web services are not accessed via object-model-specific protocols such as DCOM and Internet Inter-ORB protocol (IIOP). Instead, Web services use the lightweight SOAP protocol over Internet protocols such as HTTP, Simple Mail Transfer Protocol (SMTP), and so on. Web services are loosely coupled and allow document-centric messaging and RPCs.



Service-Oriented Architecture

InvokeService

requestor

Publish Find

Serviceprovider

Serviceregistry

Service-Oriented ArchitectureDuring development of Web services, a new pattern called Service Oriented Architecture (SOA) evolved. SOA has a service provider, a service requestor, and a service registry. Service ProviderWeb services perform a specific task or a set of tasks. For example, a Web service can be used to obtain the weather report of a given place. A service provider is responsible for developing a Web service, creating the service description, and publishing that description to one or more registries.Service RequestorA consumer of a Web service is considered a service requestor. A service requestor finds the service description in one or more registries to invoke a service.Service RegistryA service registry contains descriptions of the services that are published by service providers. Service requestors use this registry to find a service.



Web Services Constituents

• Internet for communication

• XML as universal data format

• SOAP for XML messaging

• WSDL for describing the service

• UDDI for publishing the Web services

Web Services ConstituentsThe diagram represents the Internet and various standards that are used to send messages from the service requestor to the service provider.CommunicationThe base of the stack is the Internet, because Web services use standard Internet protocols, such as HTTP, FTP, and so on, for communication.Universal Data FormatWeb services use XML for describing the functionality offered and for exchanging data between the service requestor and service provider. SOAPWeb services use the SOAP protocol for XML messaging. The SOAP protocol is used to wrap an XML message in an envelope. It provides a set of conventions for data exchange in RPCs. It is mainly used to invoke a Web service.


Web Services Constituents (continued)WSDLWSDL documents are self-descriptive. WSDL is a standard to describe the invocation syntax of a Web service. WSDL conforms to the XML syntax. By looking at the WSDL document, you know how to invoke a service.UDDIUDDI is used for publishing and querying the Web services that are described in WSDL.



Benefits of Web Services

• Distributed component model with interoperability• XML format for representing data. The request and

response messages are in the XML format.• Programming language independent• Easily accessible with standard protocols such as

HTTP, HTTPS, SMTP, and FTP• Communication through firewalls• Existing components can be exposed as

Web services to save development time.• Different communication styles:

– RPC style (synchronous)– Message style (asynchronous)

Benefits of Web ServicesDistributed Component ModelWeb services are an addition to distributed applications. Unlike other distributed component models, Web services are language independent and platform independent. Web services developed with Oracle Application Server 10g are based on Java 2, Enterprise Edition (J2EE) architecture and can interoperate with those that are developed for the .NET architecture of Microsoft.XML Format for Representing DataData encoding is a key aspect in distributed computing approaches. Representing simple data types is easy. However, mapping existing complex data types in an application to the underlying data encoding mechanisms is a difficult task. Web services use XML for representing information. The text-based form of XML eliminates byte-ordering concerns. XML’s hierarchical structure, extension capability, processing tools, and XML Schema definitions are an added advantage.Distributed systems have provided interfaces for formally describing methods and parameters. With these interfaces, the client can invoke the required service. Web services should also provide a means for describing the services and providing the information that the client needs to invoke them. This data is represented in XML. This is a major advantage because XML is neither platform specific nor vendor specific.


Benefits of Web Services (continued)Programming Language IndependentWeb services are programming language independent. They enable application-to-application communication. With Oracle Application Server 10g, any existing J2EE application and PL/SQL procedure can be exposed as a Web service. AccessibilityWeb services are accessible with standard protocols such as HTTP and HTTPS. Through Web services standards, clients and servers can communicate over HTTP regardless of platform or programming language. SOAP builds on XML and provides a standard format for invoking a Web service.Communication Through FirewallsDistributed applications are aimed at thousands of users. Communication between the client and the server has problems due to firewalls and proxy servers. The main advantage of using SOAP is that it is firewall-friendly because SOAP is layered over HTTP. Exposing Existing Components as Web Services with Oracle Application Server 10gBuilding a J2EE application involves:

• Coding the business-tier components that contain the business logic• Designing a user interface (a Web page in most cases)• Building an application (typically a servlet, JSP, or ASP) that can receive input from

the user interface and invoke an appropriate business-tier component • Formatting the response as HTML and sending the page to the client

Web Services are not dependent on HTML. Java classes and Enterprise JavaBeans (EJBs) can be directly exposed as Web Services, saving development time and improving maintainability.Communication Styles

• Synchronous: In synchronous messaging, the client and the server must be available at the same time for successful communication. The operation is not complete until the target of the message processes the request information and sends a response back to the client.

• Asynchronous: In asynchronous messaging, the client and the server need not be available at the same time. The client sends a message to the destination, and does not wait for an acknowledgement. The message can be processed at any time, and the responses arrive via callbacks.



Web Services Model

Web servicesdirectory

(UDDI)

XML interface (WSDL)

Web service

Find

Invoke Publish1

2

3

XML interface (WSDL)

Client application

Web Services ModelJava classes, stateless session EJBs, and PL/SQL procedures can be exposed as Web services with Oracle Application Server 10g. When you develop and deploy a Web service in Oracle Application Server 10g, a WSDL is automatically generated. The WSDL has information about the attributes and return types of the methods that can be invoked as Web services. The Web services are registered with the UDDI registry for lookup by the client applications.The illustration in the slide shows the following:

1. A Web service is generated and published to the UDDI registry.2. The client application browses the UDDI registry to locate an appropriate Web service.

There can be many Web services registered with a particular UDDI registry. You can find the Web service that is required by your application, and obtain WSDL definition that describes the services.

3. The client application can invoke any operation of the Web service. Operation in a Web service refers to methods that are exposed as Web services. The client can invoke them with an instance of a proxy class, just like invoking a method on the local machine.



RPC-Style Web Services

• RPC-style Web services are loosely coupled.• SOAP messages model the call and response

semantics.• This style of communication can be described in

WSDL.

RPC-Style Web Services You have already learned that Web services can use different communication styles: RPC style and message style. You now learn about RPC-style Web services. RPC-style Web services are interface driven and loosely coupled. They are synchronous. Clients use the Web service by sending parameters and receiving return values. A client sends a SOAP message that contains details about the method to be invoked and the parameters for that method. The SOAP servlet (designed to handle RPC SOAP requests) unwraps the SOAP message envelope and identifies the method to be invoked. The servlet decodes the parameters and invokes the method. The SOAP servlet encodes the return values into a SOAP response and sends it back to the client over the same protocol with which the request was sent. Therefore, the client and the server must be available at the same time to successfully complete the RPC invocation.The applications on the client and the server need not be written in the same language, unlike Remote Method Invocation (RMI), in which the client and the server are Java applications. Therefore, RPC-style Web services are loosely coupled.



Document-Style Web Services

• Document-style Web services are loosely coupled.• SOAP messages carry arbitrary XML documents.• This style of communication can be described in

WSDL.

Document-Style Web ServicesA document-style Web service follows the messaging style of communication. In document style, the Web services client sends an entire XML document to be processed by the Web service. Unlike in an RPC-style Web service, there is no concept of a method name or input/output in a document-style Web service. A document-style Web service does not model call/response semantics. Instead, it carries XML documents that can also be described in WSDL. Document-style Web services can be synchronous or asynchronous. For synchronous document-style Web service, Oracle supports certain method signatures. Clients call these methods to pass the documents, and in turn get a modified document as response. In an asynchronous document-style Web service, the messages are sent to intermediate destinations often referred to as topics or queues. These messages are then received by the actual destinations depending on their availability.RPC-style APIs require endpoints that need a good infrastructure in large-scale distributed applications. Document-style Web services communicate in a loosely coupled manner and, therefore, make it possible to develop new application behavior in a declarative manner. If XML messages describe themselves, then the senders and receivers need to know less about the infrastructure.RPC-style Web services have “RPC/Encoded” operations, and document-style Web services have “DOC/Literal” operations. “RPC/Encoded operations” and “DOC/Literal operations”are WSDL (metadata) concepts.



Oracle Support for Web Services

Oracle Application Server 10g is the infrastructure for:• Describing Web

services• Deploying Web

services• Publishing Web

services• Invoking Web

services

Oracle JDeveloper 10gprovides tools for:• Developing, deploying,

publishing, and invoking Web services

• Modeling, testing, and debugging Web services

• Browsing UDDI registry to locate Web services

• Generating stub files to consume Web services

Oracle Support for Web ServicesOracle Application Server 10g provides an infrastructure for:

• Exposing stateless/stateful Java classes, stateless session EJBs, PL/SQL procedures and functions, and Java Message Service (JMS) destinations as Web services. Oracle Application Server 10g Web services are integrated with the J2EE framework.

• Web services are described by using standard WSDL. Oracle AS provides tools to automatically generate the WSDL.

• Web services can be invoked by using standard Internet protocols. These Web services can be consumed from existing J2EE applications. Oracle Application Server 10gprovides a highly optimized Web service’s proxy client that can be downloaded and embedded into the client’s application.

Oracle JDeveloper 10g is an integrated development environment (IDE) that can be used to develop, deploy, test, and debug Web services. It can be used to model Web services with Unified Modeling Language (UML) class diagrams. It can be used to generate WSDL, client stubs, and skeletons. You can use the UDDI browser to browse the UDDI registry and locate Web services. By using JDeveloper, you can deploy the Web service either to the stand-alone OC4J or to Oracle Application Server 10g.



SOAP: XML Messaging for Web Services

• Introduces a self-describing data representation format in XML

• Represents request and response as XML messages

• Supports both RPC-style and document-style invocation

• Uses HTTP and other protocols at transport layer• Supports data encoding and literal styles• SOAP hides details of implementations; works

with:– Any programming language– Any operating system– Any hardware platform

SOAP: XML Messaging for Web Services SOAP is a lightweight, XML-based protocol for exchanging data in a distributed environment. SOAP hides the technology choices and implementation details from both parties: service requestor and service provider. SOAP is in XML and places no restriction on the format. SOAP provides a simple and lightweight mechanism for exchanging structured and typed information between peers in a decentralized, distributed environment by using XML. SOAP itself does not define any application semantics such as a programming model or implementation-specific semantics; instead, it defines a simple mechanism for expressing application semantics by providing a modular packaging model and encoding mechanisms for encoding data within modules. SOAP V1.1 describes how the data types defined in associated XML schemas can be serialized, or marshaled, over HTTP (or other transports). SOAP is transport independent. It can be layered over SMTP and FTP. Most common implementations are over HTTP. Both the publisher and the consumer of SOAP messages must have access to the same XML schemas to correctly exchange information. The schemas are typically posted on the Internet, and may have to be downloaded by one or more persons in an exchange of messages.



Communication with SOAP

Communication by using SOAP protocol includes:• Requests to invoke a service• Responses from service method• Fault from a service

SOAP client

Request

Web serverFirewallResponse

Communication with SOAPSOAP is used for communication between applications.

• A client sends a request for a service. This request is a SOAP message and is in the standard XML format. The request includes information about the recipient of the message and parameters for successfully invoking the service. This message is then handled by the Request Handler (a servlet) running on the Web server.

• The Request Handler invokes the requested service. The service returns a response to the Request Handler servlet.

• The Request Handler returns the response of the service to the client. The response includes return values from the methods.

• In case of errors while processing the request, SOAP fault codes are returned.



SOAP Messages

A SOAP message is an XML document that consists of:• A mandatory

envelope as a top-level element

• An optional header• A mandatory body• An optional fault

HTTP headers

Headers

Message name, data,and fault element

SOAP envelope

SOAP header

SOAP body

SOAP MessagesSOAP is the second generation XML protocol that uses XML schema for data types.Therefore, it is highly extensible. First generation XML protocols rely on XML1.0 and arenot extensible. SOAP does not define any application semantics such as a programming model orimplementation-specific semantics; instead, it defines a simple mechanism for expressingapplication semantics.The slide shows a SOAP message over HTTP protocol that contains the following elements:

• HTTP headers: When a SOAP protocol is used over HTTP, the packet starts with an HTTP header, which contains information about the operation, method, Content-Type, Content-Length, error codes, and the recipient of the message.

• Envelope: Envelope is a mandatory and top-level element in a SOAP message. Envelope is a wrapper for the message and defines a framework for expressing what is in a message and how to process it. The element contains namespace declarations. It can have subelements and attributes. The SOAP Envelope can contain an optional Header element, but should contain a Body element.


SOAP Messages (continued)• Header: The Header is optional. If present, Header is the first child element of

Envelope. Header is included to add features to a SOAP message without prior agreement between the communicating parties. A Header can in turn have any number of headers. These headers are included to provide additional information that is handled by infrastructure services. In a real-world scenario, login information, session information, security, transactional information, and so on, can be included in the body. However, this approach makes the SOAP message more complicated. Instead, this information can be included as multiple headers.

• Body: The Body element provides a simple mechanism for exchanging mandatory information with the ultimate recipient of the message. This element includes RPCs and error reporting. In case of request messages, the body section contains the method-specific information that is required to invoke the method. In the response message, the body section contains the return message from the Web service. In case of an error condition, the Body element can contain a Fault element.

• Fault: Fault element is used to indicate that an error has occurred and provides information about the error. This element is used to carry error or status information within a SOAP message. Fault elements appear as a body entry and must not appear more than once within a Body element.

A SOAP application should include the proper SOAP namespaces on all elements that are defined in messages. SOAP messages should not contain Document Type Definition (DTD) and Processing Instructions (PI).



Web Services DescriptionLanguage (WSDL)

• Is a description language to define Web service interfaces and how to invoke them

• Is an XML Schema for describing Web services: – Service interface definition: Describes what

message must be sent and what message is returned

– Service implementation definition: Describes to which address the message must be sent

• Allows both the messages and the operations on the messages to be defined abstractly in XML

• Answers three key questions about a Web service:– What does a service do?– How is a service accessed?– Where is a service located?

WSDLSOAP provides a standard way of transporting messages for use by Web services, whereas WSDL provides a standard way to describe Web services. WSDL is an XML format for describing Web services. WSDL describes what functionality a Web service offers, how it communicates, and where it is accessible. Because it is in the standard XML format, theservices developed can easily be made available to thousands of users. Users must invoke the correct services with the appropriate parameters. WSDL defines an XML grammar to specify the location of the service and to describe the operations of a service. A WSDL file contains the following information about an operation:

• Service interface• Implementation details• Access protocol• Contact endpoints



WSDL

<?xml version=“1.0” encoding=“UTF-8” ?><definitions name=“Hello” ...targetNamespace=“http://tempuri.org/Hello.wsdl” ...><types><schema targetNamespace=“http://tempuri.org/Hello.xsd...xmlns:xsd=“http://www.w3.org/2001/XMLSchema” />

</types><message name=“sayHelloOutput”>... </message><message name=“sayHelloInput”> ... </message><portType name=“HelloPortType> <operation name=“sayHello”> .... </operation>

</portType><binding name=“HelloBinding”> <operation> <input>..</input> <output>..</output></operation> </binding>

<service ..> <port> <soap:address location=“..” /></port>

</service></definitions>

WSDL (continued)The slide shows the various tags in a WSDL file.• <definitions>: The WSDL document starts with a <definitions> tag. This

tag encloses all other tags in the file. This tag contains a few namespace declarations. In Web services, the data that is exchanged between the client and the server must conform to XML Schema. The namespace declarations contained in the <definitions> tag point to the XML Schema definition. For communication usingthe SOAP protocol, the SOAP libraries are needed. The <definitions> tag contains the SOAP namespace that specifies where to look for these libraries.

• <types>: The <types> element encloses data type definitions for the exchanged messages. This element contains the xsd schema namespace. This schema is where you define custom types to use with messages. For interoperability and platform neutrality, WSDL uses data types as defined in the XML Schema specification. Therefore, the data types that are used to pass parameters and obtain return values must conform to xsd.


WSDL (continued)• <message>: The <message> element corresponds to the methods of the Web

services that can be invoked by a client application. For example, if a function called sayHello() is exposed as a Web service, there are two messages associated with this method: one is the input message and the other is the output message. Therefore, there are two <message> elements associated with every method of a Web service.

• <portType>: A <portType> is a set of abstract operations and their messages. The operation is the method that is exposed as a Web service. Each <portType>has a unique name identified by the name attribute. Each <portType> can consist of one or more operations. If the <portType> contains an operation called sayHello, that means a function called sayHello is exposed as a Web service. There are two messages associated with this operation: an input message and an output message. The input and output elements of the operation element correspond to these messages. These messages and their parameters are used with the <message>element that you have already learned.

• <binding>: The <binding> element is used to specify that SOAP protocol is used over HTTP. It also shows whether it is an RPC-style invocation or a document-style invocation of Web service.

• <service>: The <service> element contains the name of the Web service, the location of the Web service, and the context with which it can be accessed. A service groups a set of related ports together. It can contain zero or more port elements. The port elements specify how this service can be accessed. A port contains a network address and the binding of the Web service.

Note that the WSDL file is automatically generated and, therefore, each tag of the WSDL file is not explained in detail.



UDDI Registry

• Is an online electronic registry for registering businesses and Web services

• Is a specification for description and discovery• Supports the Publishing and Inquiry APIs to

publish and inquire about a Web service

UDDI RegistryYou have been introduced to Web services and their benefits. You have also learned that WSDL is used to describe Web services, and that the SOAP protocol is used to invoke them. To invoke a Web service, the service requestor should first discover the service and then send the SOAP message. The UDDI is a registry where businesses and Web services are registered. The requestor can use UDDI to discover a Web service.What Is UDDI?UDDI Project is an industry initiative that provides standards for publishing and discovering information about Web services. The UDDI community, which is established by several leading software vendors including IBM, Microsoft, and Oracle, runs the UDDI Project and makes its results available to the public through http://www.uddi.org/.UDDI is a directory service where businesses can register and search for Web services. It is a platform-independent framework for describing services, discovering businesses, and integrating business services.The UDDI registry can be used at a business level to discover if there are any Web service interfaces with a given type of service. UDDI serves as a mechanism for businesses to reach their customers and partners. It is used to locate information about how the service is exposed and to learn the technical details required to interact with that service.


UDDI Registry (continued)The UDDI Business Registry is a logically centralized, physically distributed service, with multiple root nodes that replicate data with each other on a regular basis. After a business registers with a single instance of the business registry service, the data is automatically shared with other UDDI root nodes and becomes freely available to anyone who needs to discover which Web services are exposed by a given business. These are public registries. You can also have private UDDI registries. To ensure that most platforms can access UDDI’s services, the UDDI directory exposes a set of APIs. These APIs fall under two main categories: Inquiry and Publishing. To involve these APIs, you must send SOAP messages with appropriate body content. The SOAP response that comes back from UDDI contains the businesses that match the search criteria.



How UDDI Is Used

UDDI BusinessRegistry

Business portals andmarketplaces

Business user Software developer

UDDI Registry

Businessdescriptions

Servicetypes

How UDDI Is UsedUDDI can be used in a number of different ways, based on the perspective of the user. For example, a business user can browse one or more UDDI registries to view the different businesses that expose Web services. However, business users will not use the UDDI registry directly, because the UDDI APIs are not necessarily user-friendly. Instead, business users might use business search portals, marketplaces, or other tools that provide a more user-oriented interface. Tools such as portals and marketplaces use the UDDI Inquiry API to access the registry data. Software developers can use the UDDI Publishing API to publish services. They also might programmatically query the registry to discover services dynamically.The UDDI Business Registry is a conceptually single system that can be built from multiple nodes, called Operator Sites, that have their data synchronized through replication. The UDDI Business Registry is a public registry that anyone can use.A company can set up a private registry that is not part of the public UDDI Business Registry, for its internal use. Private registries can define the access rules of their nodes for different users.



Searching for a Web Service by Using UDDI

Provider infoContact InfoDirectory ofnames

White pages

Yellow pages

Search using context such as location, service type. Point to White pages for details.

Green pages

Information about business modelTechnical details of provided serviceInformation on business process

Searching for a Web Service by Using UDDIThe UDDI registry contains three types of information that are referred to as the white, yellow, and green pages. White PagesWhite pages contain basic contact information about a company, including name, address, and contact information. This information allows users to search for businesses and to locate Web services based on the company’s business identification. Yellow PagesYellow pages contain high-level service information, such as service name, a human-readable service description, a list of categories to which the service belongs. This information allows users to discover a Web service based upon its categorization. Services can be categorized by several taxonomies such as North American Industry Classification System (NAICS), Universal Standard Products and Services Classification (UNSPSC), and ISO 3166 Geographic Taxonomy. Green PagesGreen pages contain low-level information required to invoke services. This includes business processes, service descriptions, and binding information. Binding information supplies the service location and protocol that is used to communicate with the service.



UDDI Specification

• UDDI Programmer’s API• UDDI Data Structure Specification and XML

Schema• UDDI Replication Specification and UDDI XML

Replication Schema• UDDI Operator’s Specification

UDDI Specification (Version 2.0)The UDDI Specification consists of the following set of specification and XML schema documents:

• The UDDI Programmer’s API specification defines a set of functions that all UDDI registries support for inquiring about services hosted in a registry, and for publishing information about a business or a service to a registry. This specification defines a set of SOAP messages containing XML documents that a UDDI registry accepts.

• The UDDI Data Structure Specification describes the XML structures that are contained within the SOAP messages defined by the UDDI Programmer’s API. This specification defines five core data structures and their relationships to each other. The UDDI XML Schema is not a specification document, but an XML Schema document that defines the structure and data types of the UDDI data structures.

• The UDDI Replication Specification describes the data replication process and the API that is required to accomplish data replication between UDDI Operator Nodes.

• The UDDI Operator’s Specification describes the behavior and operational parameters that are required by UDDI Node Operators. (This specification defines no programmer’s API, and is not relevant for private registries.)



tModel

• Provides metadata information about a Web service specification

• Contains references to the specification locations• Is used for compliance check

tModel

A <tModel> is an abstract description of a particular specification of the Web service. A <tModel> is a type of digital “fingerprint” for determining the specifics of how to interact with a particular Web service. The <tModel> structure does not provide the Web service’s specification directly. Instead, it contains pointers to the locations of the actual specifications. Companies can use the information pointed to by a <tModel> to determine whether a Web service is compatible with their business requirements.The relation between businessService and tModel is described as follows: <businessService> has a <bindingTemplate> that contains one or more <tModelInstanceInfo> documents. Each <tModelInstanceInfo> document contains a tModelKey attribute that is the Universal Unique Identifier (UUID) of a <tModel> document, representing information about the supporting specification.When businesses want to make their specification-compliant services available to the registry, they include a reference to the tModelKey attribute for that service type in their <bindingTemplate>.



<tModel tModelKey="uuid:7716711A-1231-483F-A4B9-36104341BA78" operator=“…” authorizedName=“…”><name>Airport Weather</name><description xml:lang="en">Web Service to check weather on intl. airports

</description><overviewDoc><description … >…</description><overviewURL>

http://live.capescience.com/wsdl/AirportWeather.wsdl</overviewURL>

</overviewDoc>...

</tModel>

tModel

tModel (continued)The slide shows a fragment of the tModel structure. Each <tModel> contains a UUID as a tmodelKey attribute. UUIDs are unique hexadecimal strings that are generated when the data structure is first inserted into the UDDI registry. The tModel name identifies the service. In this example, Airport Weather is the service. The description supplies explanatory information. The tModel also contains an <overwiewDoc> entry which in turn contains an <overviewURL> entry. This URL points to the service WSDL description. A <tModel> has several uses in the UDDI registry. The most common use is to represent a technical specification or concept. The designer of a specification or a concept publishes information about the specification by registering it in an UDDI registry as a tModel. Thus, a tModel identity is defined in the registry, but the actual specification or set of documents that describes the concept of a tModel is not a part of the registry. Instead, it is remotely referenced by the <overviewDoc> structure.


How WSDL Relates to UDDI Data StructureWSDL is used to describe the interface of a Web service. It contains an abstract specification of the service, including specification of service parameters, their types, and communication protocols. A WSDL interface can also contain information that is specific to a particular service instance. This information is defined in the <service> and <port>elements that identify the actual service location (the URL of the Web service). If a service is used within the context of UDDI, both parts, the abstract interface definition and the service specific information, can be separated. The abstract service interface definition can be registered in a UDDI registry as a tModel with the <overviewDoc>structure pointing to the WSDL document that describes the service. Such tModelstructures are referred to as “wsdlSpec tModels.” Service providers, who want to provide a service that is compliant to the specification, retrieve a tModel and use the WSDL pointed by it for the service implementation. A new service can then be registered in an UDDI registry. It is represented by the <businessService> data structure, which contains a <bindingTemplate> for each service access point. Furthermore, the <bindingTemplate> includes a <tModelInstanceInfo> element for each wsdlSpec <tModel> that describes the interfaces and bindings supported by the service. The WSDL pointed to by the tModel does not contain the <service> and <port>elements. These service location–specific information is specified as an <accessPoint>element in the <bindingTemplate>. Consider an example:

<tModeltModelKey="UUID:7F1DA096-B073-48C1-9B21-FE9613CA8FA4" operator=„..." authorizedName=„..."><name>Address Correction for USA addresses WSDL-interface</name>

<description xml:lang="en">Corrects Postal Addresses. Converts Zip Codes to City Names

</description><overviewDoc>

<description xml:lang="en"/><overviewURL>

http://ws.cdyne.com/psaddress/addresslookup.asmx?wsdl</overviewURL>

</overviewDoc><categoryBag><keyedReference

tModelKey="UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4"

keyName="uddi-org:types" keyValue="wsdlSpec" /> </categoryBag>

</tModel>


How WSDL Relates to UDDI Data Structure (continued) This tModel also contains a <categoryBag> element that has a tModelKey. In this context, the tModel is used for categorization. A <tModel> that references a WSDL document has a categorization taxonomy of uddi-org:types and categorization value of wsdlSpec that are used in the <categoryBag> element. When a <tModel> refers to a WSDL document, it refers to the entire content of thedocument, including all of its bindings. If a <tModel> should refer to a single binding, then a fragment identifier is used in the <overviewURL>. The name of this particular binding is used after the hash sign in <overviewURL>. For example:

<overviewURL> http://stockquote-definitions/stq.wsdl#StockQuoteSoapBinding</overviewURL>

<tModel> refers specifically to StockQuoteSoapBinding.



UDDI Support in Oracle JDeveloper 10g

JDeveloper provides a UDDI browser with which you can:• Define a connection to a UDDI registry instance• Search for services:

– Look up tModel by name or category– Locate a service implementing this tModel– Add a business providing this service to the UDDI

browser• For the located service:

– Generate Web service stub/skeleton – View WSDL– View a business that provides the service

UDDI Support in Oracle JDeveloper 10gUDDI BrowserOracle JDeveloper 10g provides a built-in UDDI browser. You can locate and use Web services in an external UDDI registry or in a private UDDI registry. You can use the Oracle JDeveloper 10g UDDI browser to define a connection to a specific UDDI registry instance, and then to search for a specific Web service. After a desired Web service is found, JDeveloper can generate a proxy stub to invoke the located service programmatically. Define UDDI Registry ConnectionIn the Oracle JDeveloper 10g Navigator panel, under the Connections node, you can find the “UDDI Registry” entry. Expanding this entry shows a number of predefined UDDI registry connections. You can use these existing connections or you can define new ones to other UDDI registries by using a UDDI Registry Connection Wizard. The wizard prompts you to provide the Connection Name and the Inquiry URL for the Registry instance.



UDDI Browsing with Oracle JDeveloper 10g

UDDI Browsing with Oracle JDeveloper 10gFind ServicesYou can search for a specific service for a selected UDDI connection by using a Find Web Services Wizard. To start this wizard, right-click any UDDI registry and select Find Web Services. You can use the wizard to search for a tModel by name or category, and then to select existing services from the list of businesses that provide the implementation of the specified tModel. The wizard provides several options for a located service. They are:

• Generating the stub code for service invocation. The stub is generated and added to an existing project. The business that provides the service is added as a node in the Navigator tree.

• Opening the end point of this service in the browser• Displaying a description for the located service • Adding the business to the UDDI browser for further navigation or actions

Generate StubAfter a specific service is located, the Oracle JDeveloper 10g Web Service Stub/Skeleton Wizard can be used to generate a client-side stub for service invocation or a server-side skeleton for the service implementation. The wizard uses the WSDL of the service that was previously located in UDDI. You can select the operations that are defined in the WSDL for which the stub code must be generated.



UDDI Publishing and Browsing with Oracle Enterprise Manager

Using Oracle Enterprise Manager Application Server Control, you can:• Browse and register services within the UDDI

registry• Publish Web services and deploy them to a J2EE

container• Monitor and administer Web services

UDDI Publishing and Browsing with Oracle Enterprise ManagerWith Oracle Enterprise Manager Application Server Control, users can manage all their UDDI registry instances from a single console. Oracle Enterprise Manager provides intuitive service browsing and registration. Users can search services based on keyword, service name, service ID, and category information.Oracle Application Server administrators can easily publish Web services as part of the J2EE application deployment wizard. In addition, users can administer J2EE container services for monitoring and logging Web service activities such as up-time, response-time, throughput, CPU, and memory consumption, setting up service failover plans, defining Web service access timeouts, and specifying service access credentials.



Summary

In this lesson, you should have learned how to:• Provide an overview of Web services technology• Identify the standards used by Web services • Identify the benefits of Web services• Locate and invoke Web services by using SOAP,

WSDL, and UDDI• Distinguish between RPC-style and Document-

style Web service

SummaryIn this lesson, you should have learned about Web services. You should have also learned about standards such as SOAP, WSDL, and UDDI. This lesson discussed the benefits of Web services and the different styles of Web services.




This practice covers revision questions on Web services technology and standards such as SOAP, WSDL, and UDDI.

Practice 18-1: OverviewThe practice consists of paper-based questions on Web services technology and the standards such as SOAP, WSDL, and UDDI.


Practice 18-1Paper-Based Questions

1. Identify three features of Web services.a. Self-describing business functionb. Interfaces for a client to invoke a business functionc. Service orientedd. Component basede. Language dependent

2. Which three of the following can be exposed as Web services with Oracle Application Server 10g?

a. Stateless/stateful Java classesb. C programsc. PL/SQL stored proceduresd. Stateless session EJBse. Stateful session EJBs

3. SOAP is: (Choose two correct answers.)a. A heavyweight protocolb. An XML-based protocolc. Always layered over HTTPd. Request oriented and response oriented

4. Which three of the following statements regarding a SOAP message are true? a. It should have Envelope as top-level element.b. If Envelope is not present, Header should be the top-level element.c. If Header is present, then it should immediately follow the Envelope

element.d. It should have a Body, but need not have a Header element.e. It should have an Envelope, Body, and Header, irrespective of their order.

5. Match the elements of a SOAP message in column A to the appropriate statements given in column B.

6. WSDL is used for: (Choose two correct answers.)a. Locating a Web serviceb. Describing a Web servicec. Invoking a Web serviced. Sending messages

A B 1. Envelope a. Is a mandatory element that contains method-

specific information

2. Header b. Is the top-level element in the SOAP message and contains namespace declarations

3. Body c. Is an optional element that encapsulates data not specific to the method


Practice 18-1 (continued)7. UDDI is: (Choose one correct answer.)

a. Universal Directory Difference Informationb. Universal Discovery Directory Interfacec. Universal Description, Discovery, and Integration

8. Which of the following statements regarding UDDI are true? (Choose three correct answers.)

a. An online electronic registryb. Specification for description and discoveryc. A registry with key and value paird. Uses WSDL to describe a service e. Enables search on only one criteria


Distributing Modular Applications: Developing Web Services



Objectives

After completing this lesson, you should be able to do the following:• Identify the components that can be exposed as

Web services with Oracle Application Server 10g• Develop, deploy, and test a stateless Java class

Web service by using Oracle JDeveloper 10g• Use the Web services home page to test the

deployed Web service• Identify the steps that are involved in exposing a

PL/SQL stored procedure as a Web service

Objectives This lesson describes how to expose a stateless Java class as a Web service. You learn to use Oracle JDeveloper 10g to develop and deploy a stateless Java Web service. This lessonshows you how to create a client to invoke a Web service. It also discusses the steps involved in exposing a PL/SQL stored procedure as a Web service.



Oracle Application Server 10gWeb Services

Oracle Application Server 10g Web services can be implemented as any of the following:• Stateless and stateful

Java classes• Stateless PL/SQL

packages• Stateless session

Enterprise JavaBeans (EJBs)

• Java Message Service (JMS) destinations

Oracle Application Server 10g Web Services Oracle Application Server 10g supports building Web services from stateless Java classes and stateful Java classes, stateless PL/SQL packages, and stateless session EJBs. Java Message Service (JMS) destinations can also be exposed as Web services. This lesson describes how to develop and deploy stateless Java classes and PL/SQL packages as Web services.



Developing a Web Service with a Stateless Java Class

1. Define an interface.2. Define a stateless Java class.3. Generate an .ear file.4. Deploy the generated .ear file to Oracle

Application Server 10g.

Developing a Web Service with a Stateless Java Class Developing a Web service with a stateless Java class involves the following steps:

1. Writing an interface (optional)2. Writing a stateless Java class3. Generating the .ear file that can be deployed to Oracle Application Server 10g4. Deploying the generated .ear file to Oracle Application Server 10g

Oracle JDeveloper 10g simplifies the creation of Web services. You can use JDeveloper 10gto create, deploy, and test the Web service. The following few slides show you how to create a Web service with a stateless Java class.



Defining an Interface

Defining an InterfaceThe example used is a stateless Java class that is exposed as a Web service. The HelloWeb service contains a sayHello() method, which takes a String as parameter and returns a String when it is invoked.Why Define an Interface?Writing an interface is optional. If an interface is not defined for a class, then the Web service deployment exposes all public methods that are defined in the Java class as Web services. You define an interface to limit the exposure of methods to a subset of the public methods within a class. Although a class can contain n number of public methods, it is not necessary to expose them all as Web services to clients. Therefore, an interface can contain declarations of methods that can be exposed as Web services.Creating the Interface Using JDeveloper 10gCreate a workspace and a project. Right-click the project and select New Java Interface as shown in the slide. Provide a name for the new interface. Observe that the name Hello is used for this example. The interface will be created. You have to define the methods of the interface.The slide shows the interface called Hello. It declares a single method, sayHello(), that takes a String as parameter and returns a String.



Defining an Interface

Defining an Interface (continued)In the interface, declare a single method, sayHello(), that takes a String as parameter and returns a String. The slide shows the method in the interface.



Defining a Stateless Java Class

Defining a Stateless Java ClassAfter the interface is defined, the next step is to define a Java class. Right-click the project and select New Java Class. Provide a name for the class. Observe that the name HelloImpl is used for this example.



Defining a Stateless Java Class

Defining a Stateless Java Class (continued)The Java class (whose methods will be exposed as Web services) must include a public constructor that takes no arguments. The HelloImpl class contains the implementation for the sayHello() method declared in the Hello interface. This method takes a String as parameter, appends that parameter to “Hello” and returns the result String to the client. Although this class can have any number of methods, only the sayHello() method can be exposed as a Web service. Note that the class does not implement the interface Hello, though you have defined an interface with the sayHello() method and implemented that method in the HelloImpl class. The details of the interface and the implementation class are provided in the configuration file that is used to generate the Enterprise Archive (EAR) file.If you are using stand-alone Oracle Application Server 10g Containers for J2EE (OC4J) or Oracle Application Server 10g, then you have to create the config.xml configuration file that contains the details of the interface and the implementation class. The WebServicesAssembler (WebServicesAssembler.jar) uses this config file to create the EAR file for the Web service. If you are using JDeveloper 10g, then the config file is created automatically when you create the Web service.


Defining a Stateless Java Class (continued)There is a restriction on the data types of parameters and return types of the methods that are exposed as Web services. The following table shows the supported data types.

Primitive Types Object Types boolean java.lang.Boolean byte java.lang.Byte double java.lang.Double float java.lang.Float int java.lang.Integer long java.lang.Long short java.lang.Short java.lang.String java.util.Date org.w3c.dom.Element org.w3c.dom.Document org.w3c.dom.DocumentFragment JavaBeans Single-dimension arrays of types mentioned in the

table



Creating the Web Service

Creating the Web ServiceYou have already created the interface and the implementation class by using JDeveloper 10g. You will now create a Web service from the Java class. Right-click the Java class and select Create J2EE Web Service. Check the System-Navigator to see the files that are created for the Web service. The web.xml and WebServices.deploy files are generated. The MyWebService1 shown under the demo1.jpr in the System-Navigator is the Web service that is created. It consists of the IMyWebService1.java and the IMyWebService1.wsdl files. In the System-Navigator, if you click the Show Categories icon (that resembles three folders placed one below the other with a line next to them), then you see the various Web service files that are created, such as WEB-INF, web.xml, and the deployment files.



Creating the Client Application

Creating the Client ApplicationCreate a client application to test the Web service. Right-click the Web service as shown in the slide and select Generate Sample Java Client.



Creating the Client Application

Creating the Client Application (continued)The Java client created is the EmbeddedMyWebService1Stub.java file as shown in the slide. In the code editor, look for a commented line that says “Add your code here,” and add the method invocation. In the example, the following statement is used to invoke the Web service:

System.out.println(stub.sayHello(“Web Services”));



Deploying the Web Service

Deploying the Web ServiceRight-click the Web service and select Run. The embedded OC4J server of JDeveloper 10gwill start and the Web service will be deployed to the OC4J server. Observe the Log window and note the URL that you can use to access the Web service.



Testing the Web Service

Testing the Web ServiceRight-click the Java client and select Run. The output is displayed in the Log window.



Web Service Home Page

A Web service home page provides: • A link to the service description (WSDL file)• Links to Web service test pages to test the

available operations of the Web service• Links to the Web service client-side Proxy Jar• Links to the Web service client-side Proxy Source

Web Service Home Page Oracle Application Server 10g provides a Web service home page for each deployed Web service. To access a home page, enter a service endpoint (URL) that is displayed in the Log window when you deploy the Web service.



Testing the Deployed Web Service with Home Page

Testing the Deployed Web Service with Home PageThe slide shows the home page of the Web service. Click the “Service Description” link to access the WSDL file. You can also retrieve the WSDL file with the URL http://host:port/URI?WSDL, where URI is the path for the Web service. The MyWebService1 service has a single operation called sayHello. Click the link “sayHello”to invoke the operation.



Testing the sayHello Operation

Testing the sayHello OperationWhen you click the sayHello link, you see the page where you can provide the parameter to invoke the sayHello operation. Enter the parameter in the text field as shown and click the Invoke button to invoke the operation.



Testing the sayHello Operation

Testing the sayHello Operation (continued)When you click the Invoke button, you see the Simple Object Access Protocol (SOAP) response for the Hello Web service as shown in the slide.



Serializing and Encoding Parameters and Results

• Oracle Application Server 10g Web services support a prepackaged implementation for handling encoding, decoding, serialization, and deserialization.

• Oracle Application Server 10g supports the following encoding mechanisms:– Standard SOAP v.1.1 encoding– Literal XML encoding

Serializing and Encoding Parameters and ResultsThe parameters that are passed from the client are serialized and encoded in XML. These parameters are decoded and deserialized when the Web service receives the request. Similarly, the results or return types are serialized and encoded when they are sent from the server to the client. They are deserialized and decoded when the client receives the response.The prepackaged mechanism of Oracle Application Server 10g makes the encoding and decoding transparent to the Web service developer and the client application that invoke the Web service.Standard SOAP, Version 1.1 EncodingUsing standard SOAP, version 1.1 encoding, the server-side Web services servlet, which calls the Java class implementation, handles serialization and encoding internally for the types that are supported by Oracle Application Server 10g Web services. Literal XML EncodingBy using Literal XML encoding, a Web service client can pass as a parameter, or a Java service can return as a result, a value that conforms to W3C Document Object Model (DOM) org.w3c.dom.Element. When an Element is passed as a parameter to a Web service, the server-side Java implementation processes the Element.For return values that are sent from a Web service, the Web services client parses or processes org.w3c.dom.Element. This style is mainly used for document-style Web services



Developing a Stored Procedure Web Service

1. Set up data sources in OC4J by configuring the data-sources.xml file in the ORACLE_HOME\j2ee\home\config folder.

2. Generate the Java wrapper classes for the PL/SQL package and generate the EAR file.

3. Deploy the EAR file to Oracle Application Server 10g or stand-alone OC4J to expose it as a Web service.

Developing a Stored Procedure Web ServiceYou have seen how to develop Web services with stateless Java classes. Now you will see how to develop and deploy a PL/SQL stored procedure Web service.PL/SQL stored procedures can be exposed as Web services by generating Java wrapper classes for the procedures. These wrapper classes are generated by the JPublisher tool. Therefore, you need not recode the functionality of the existing PL/SQL procedures in a different programming language to make them available as Web services.Developing a stored procedure Web service involves the following steps:

1. Set up data sources in data-sources.xml file.2. Generating the Java wrapper classes for a PL/SQL package. You need not explicitly

invoke the JPublisher tool to generate the classes. Oracle JDeveloper implicitly invokes JPublisher.

3. Generating the EAR file4. Deploying the procedure as a Web service to Oracle Application Server 10g or stand-

alone OC4J



Generating Wrapper Classes Using JPublisher

Database JPublisher Java classes

Generating Wrapper Classes Using JPublisher JPublisher is a utility, written in Java. It is used to generate Java classes to represent the user-defined database entities such as SQL object types, SQL collection types, and PL/SQL packages in your Java program.JPublisher generates classes for PL/SQL packages. These classes have wrapper methods to invoke the stored procedures in the PL/SQL packages. The wrapper methods generated by the JPublisher tool contain SQLJ code. When JPublisher generates wrapper methods, it generally produces .sqlj source files. You can use the –methods option of JPublisher to indicate that no wrapper methods should be generated. Then, JPublisher produces .javasource files.To expose a stored procedure or function as a Web service, you need not explicitly use JPublisher to create the Java source files. JDeveloper invokes JPublisher to create them.



Exposing a Function as a Web Service by Using Oracle JDeveloper 10g

Exposing a Function as a Web Service by Using Oracle JDeveloper 10gA connection is established to the database from JDeveloper. The screenshot shows that the schema has a package called emp_pack. This package has a function called get_namethat takes an employee number as a parameter and returns that employee’s first name and last name.You will now see how to expose this function as a Web service.



Publishing the Package as a Web Service

Publishing the Package as a Web Service Right-click the package body or package in the System-Navigator. Select “Publish as Web Service…” from the context menu. You see the PL/SQL Web Service Publishing Wizard screen. The wizard takes you through the steps to publish the PL/SQL function as a Web service.A stateless session bean can also be exposed as a Web service. The steps to be followed to expose a stateless session bean as a Web service are the same as those involved in exposing an existing Java class as a Web service. In the practice for this lesson, you expose a stateless session bean created in lesson 12 as a Web service.



JMS Web Services

• Oracle Application Server 10g supplies a servlet to support two operations on messages:– Send operation – Receive operation

• The JMS Web service determines how to handle incoming and outgoing messages from JMS destinations.

• JMS messages can be processed on the server side by:– Message-Driven Bean (MDB) – JMS client

JMS Web Services With Oracle Application Server 10g, you can create JMS Web service that puts messages on and takes messages off JMS destinations. Oracle Application Server 10g supplies a servlet that supports two operations on messages:

• Send operation: If the destination is a JMS Queue, then send means enqueue. If the destination is a topic, then send means publish the message. The client supplies an XML element and the Web service enqueues this on JMS destination.

• Receive operation: If the destination is a JMS Queue, then receive means dequeue. If the destination is a topic, then receive means consume the message. The Web service dequeues a message from a specified destination and return it to the client.

An individual JMS Web service can support the send operation, or the receive operation, or both operations, as determined by the service developer. The Web services run-time verifier throws an exception if the operation supplied by a JMS Web service client is invalid. For example, if the deployment operation is send, and the request is receive, then an exception is thrown.


JMS Web Services (continued)The JMS Web service only exposes JMS destinations. The messages are processed either by an MDB or a JMS client on the server. A JMS Web service either sends messages to a JMS destination or receives messages from a JMS destination and can use an MDB on the back end to receive messages. Because JMS uses MDB for generating and consuming messages, it is important to define MDBs.



Summary

In this lesson, you should have learned how to:• Expose a stateless Java class as a Web service• Test the Web service with the Web service home

page• Use Oracle JDeveloper 10g to develop, deploy,

and test Web services• Expose a PL/SQL stored procedure as a Web

service

SummaryIn this lesson, you should have learned how to expose a stateless Java class as a Web service, and how to develop and deploy Web services from Java classes by using Oracle JDeveloper 10g. You should have also learned how to use Web services home page to test the deployed Web service, and how to write a client application to invoke the Web service.You have learned that a PL/SQL stored procedure can be exposed as a Web service by:

1. Creating Java wrapper classes by using Jpublisher.2. Creating an EAR file.3. Deploying the EAR file to Oracle Application Server 10g or stand-alone OC4J.




This practice covers the following topics:• Exposing a stateless session bean as Web service

by using Oracle JDeveloper 10g• Deploying the Web service to an embedded OC4J

server and testing it with a client application• Deploying the Web service to Oracle Application

Server 10g and testing it with the Web services home page


Practice 19-1The purpose of this practice is to expose a stateless session EJB as a Web service. You expose the ValidateCard session bean created in practice 12 as a Web service. Perform the following steps to expose the validate(String s) method of the ValidateCard session bean as a Web service.

1. Expose the ValidateCard session bean as a Web service:a. Open the workspace practice12oneske.jws . You can use this workspace

if you have successfully completed practice 12-1. Otherwise, use practice12onesoln.jws.

b. Right-click the project; select New. Choose Web Services from the Business node of Categories and select Java Web Service from Items.

c. Click OK. You see the Web Service Publishing Wizard. Click Next.d. Browse to select the ValidateCard remote interface. Click Next.e. Select the validate(java.lang.String) method and click Next. In the

Web Service Endpoint change the Web Server Port to 8988, because the embedded OC4J runs on port 8988. JDeveloper picks the port number from here and generates the WSDL file. The endpoint in the WSDL file has the same port number. Click Next and then click Finish.

f. Note that the Web service, MyWebService1, and the Webservices.deploy files are generated.

2. Generate a client to test the Web service with embedded OC4J.a. Right-click the Web service and select Generate Sample Java Client.b. The sample client is generated. Check the port number in the String endpoint in

the client application.c. Edit the client and add the following line to the try block of the main method:

System.out.println(stub.validate(“BN349672A”));3. Run the Web service and the client application:

a. Right-click the Web service and select Run. Note: Check the port on which embedded OC4J runs and make sure that the string endpoint in the client application (created in step 2 b) has the same port number, or change the port number in the client program.

b. Right-click the client application and select Run. You should see the following line displayed in the Log window:THANKYOU FOR PROVIDING YOUR CUSTOMER CARD NUMBER

Note: If you see any SOAP exceptions when you run the client application, then it is because of port conflicts.


Practice 19-1 (continued)4. Deploy the Web service to Oracle Application Server 10g by performing the following

steps:a. Right-click the WebServices.deploy file in the System-Navigator and

select Deploy to <connection> if a connection to Oracle Application Server 10g already exists. Otherwise, select Deploy and then select New Connection. The Connection Wizard is displayed. Click Next.

b. Type Connection1 for Connection Name, select Oracle Application Server 10g from the Connection Type drop-down list. Click Next.

c. Provide the username and password. Click Next.d. Specify the Oracle Home directory. Click Next.e. Type welcome for the Remote Method Invocation (RMI) password. Click Next.

Click the Test Connection button to test your connection. Wait to see the status “Success” and then click Finish.

f. You see the deployment messages in the Log window. Wait for the process to complete.

g. Start Internet Explorer, type the following URL to go to the Enterprise Manager Application Server Control: http://hostname:1810. Enter User Name and Password.

h. Click home under System Components. Click the Applications link. You will find a link for your application in the Deployed Applications list. Click the link to see the details of the deployed application. You will see the WebServices link under Web Modules.

i. Note the URL binding for this application and the name of the application.In this example, the URL binding is /practice12oneske-validatecard-context-root and the name is MyWebService1.

j. You can now access the Web service with the URLhttp://localhost:7777/practice12oneske-validatecard-

context-root/MyWebService1.k. You will see the Web Services home page.l. Click the validate link. Enter the string BN349672A in the text field and click

Invoke.m. You can see the SOAP response from the Web service.


Implementing Security in J2EE Applications



Objectives

After completing this lesson, you should be able to do the following:• Define Java Authentication and Authorization

Service (JAAS)• Define security issues regarding Web applications

and Enterprise JavaBeans (EJB)• List the security attributes of the Java Naming and

Directory Interface (JNDI) Context interface

ObjectivesIn this lesson, you learn how to configure security for your Java 2, Enterprise Edition (J2EE) applications, because different clients can access your Web applications and EJB components. You also examine how to edit the deployment descriptor to declaratively (instead of programmatically) control access to Web applications and EJB components so that only authorized clients can access the required functionality.



Goals of J2EE Security Architecture

• Lessen the burden of the application developer in securing applications

• Ensure fine-grained access control to the EJB resources

• Enable portable and secured Web applications and EJBs

Goals of J2EE Security ArchitectureSecurity is a critical issue in the development and deployment of the J2EE applications. The goals of the J2EE security architecture are:

• To ease the bean developer’s burden of coding the security mechanism. The security details need not be coded into the bean but can be controlled declaratively by specifying the details in the deployment descriptor when either the application package is assembled or at the time the application is deployed.

• To provide a fine-grained security mechanism so that an application and its methods can be accessed only by authenticated and authorized users. You can control access to the Web application functionality, based on a URL pattern, or method specifications in an EJB component.

• To provide a flexible architecture that allows the Web applications or EJB to be used in any security environment. This enables the applications to be portable across multiple J2EE containers.

These goals assume that the developer may not have any idea of the target security environment and its requirements. Instead, the application deployer can customize, or map the security policies in the deployment descriptor, depending on the operational environment in which the applications are being deployed.



Overview of J2EE Security Architecture

Use Java Authentication and Authorization Service (JAAS) APIs to:• Authenticate a client to access the system

– Define security identities (principal/users), groups, and roles to identify clients to the container

– Associate principals to the client to enable access to the bean methods

• Authorize clients to access the bean methods – Define logical roles, set method permissions, and

map roles to users in the deployment descriptors– Use containers to authorize the client requests to

the methods

Overview of J2EE Security ArchitectureThe J2EE security architecture involves the authentication and the authorization of clients to the system and, for an EJB, the individual methods of the bean.Oracle Application Server 10g supports JAAS by implementing a JAAS provider. The JAAS provider enables application developers to integrate authentication and authorization services into their applications environments. Instead of allocating resources to developing these services, application developers can focus on the presentation and the business logic of their applications. Authentication is the process of verifying the identity of a user, device, or any other entity in a computer system, often as a prerequisite to granting this entity access to resources in a system. For example, when a user enters a username and a password to access the resources on a computer (such as a database) before being permitted access to these resources, the user must first be authenticated (verified) by means of the login information.Authorization is the process of verifying whether a particular method call request from a client should be allowed to execute the method. After a user is authenticated, the authorization process occurs. Authorization is the process of determining if the authenticated user has the right to perform the requested operation (such as updating a table in a database).



Java Authentication and Authorization Service (JAAS)

JAAS is a framework that:• Provides a Java API package to enable

applications to authenticate and enforce security• Allows definition of logical security names that are

mapped in deployment descriptors to users or roles defined in the run-time environment

• Controls access to Web applications based on URL patterns

• Allows fine-grained authorization to manage how clients can access bean methods

A JAAS provider implements the JAAS framework and applies the Java2 Security Model.

Java Authentication and Authorization Service (JAAS)The JAAS provider implements JAAS and its policies, and integrates with J2SE and J2EE applications that use the Java2 Security Model. JAAS extends the access control architecture of the Java2 Security Model to support principal-based authorization.Policies contain the rules (permissions) that authorize a user to use resources, such as reading a file. Permissions are the basis of the Java2 Security Model. Each permission represents a specific access to a particular resource. All Java classes (whether run locally or downloaded remotely) are subject to a configured security policy that defines the set of permissions that are available for those classes. You can use the Java2 Security Model to configure security at all levels of restriction. This provides developers and administrators with increased control over many aspects of enterprise applet, component, servlet, and application security.JAAS is designed to complement the existing code-based security in JDK 1.3. JAAS implements a Java version of the standard Pluggable Authentication Module (PAM) framework, enabling an application to remain independent from the authentication service. The Web application security involves authentication and authorization of clients based on URL patterns, and the EJB security architecture allows fine-grained access control to the individual methods of a bean.



Java Authentication and Authorization Service (JAAS)

JAAS supports the following authorization, authentication, and user community (realm) features:• Principals• Subjects• Login module authentication• Roles• Realms• Policies• Permissions

Java Authentication and Authorization Service (JAAS) (continued)JAAS supports the following authorization, authentication, and user community (realm) features:

• Principals: A principal is a specific identity, such as a user named Smith or a role named HR. A principal is associated with a subject on successful authentication to a computing service.

• Subjects: A subject represents a grouping of related information for a single user of a computing service, such as a person, computer, or process. Such information includes the subject’s identities and security-related attributes (such as passwords and cryptographic keys). Subjects can have multiple identities, where principals represent identities in the subject. A subject becomes associated with a principal (user Smith) on successful authentication to a computing service; that is, the subject provides evidence (such as a password) to prove its identity.

• Login module authentication: To associate a principal with a subject, a client attempts to log in to an application. In login module authentication, the LoginContext class provides the basic methods that are used to authenticate subjects such as users, roles, or computing services.

• Roles: JAAS does not explicitly define roles or groups. Instead, roles or groups are implemented as concrete classes that use the interface java.security.Principal.


Java Authentication and Authorization Service (JAAS) (continued)• Realms: JAAS does not explicitly define user communities. However, the J2EE

Reference Implementation (RI) defines a similar concept of user communities called “realms.” A realm provides access to users and roles (groups) and optionally provides administrative functionality.

• Policy: A policy is a repository of JAAS authorization rules. The policy includes grants of permissions to principals, thereby answering the following question: Given a grantee, what are the granted permissions of the grantee? Policy information is supplied by the JAAS provider, which can be file based or can use a Lightweight Directory Access Protocol (LDAP) server.

• Permissions: Permissions are the basis of the Java 2 Security Model. All Java classes (whether run locally or downloaded remotely) are subject to a configured security policy that defines the set of permissions available for those classes. Each permission represents a specific access to a particular resource. A permission instance comprises a class name (such as java.io.FilePermission), a target or resource to which the permission applies (for example, a directory pattern such as /home/*), and a set of actions associated with the target (such as read, write, and/or execute).



Authorization of a Client

• The authorization is specified in the J2EE-specific and OC4J-specific deployment descriptors.

• Security roles– Define the security view of the application to the

deployer– Must be mapped to the appropriate security

principals in the target environment• Every client obtains a security principal.• A client can invoke a URL or a method only if the

client’s role has the associated invocation rights.• The container provider enforces the security

policies and provides the tools for managing security.

Authorization of a ClientThe security roles that are defined by the application assembler provide the deployer with a logical and simplified security view of the Web application, or the EJB. The deployer is responsible for mapping the logical security roles to principals or to groups of principals that are defined in the target operational environment.At run time, a client is allowed to access a URL or invoke a business method only if the principal making the request is authenticated and authorized (by being associated with an appropriate security role) to access the requested resource. The container provider enforces the security policies at run time and provides the tools for managing security during deployment and at run time.The security view defines the various types of users of the application and their rights to invoke a URL request or methods in the enterprise bean interfaces. Note: The security roles define the logical security view of an application. They should not be confused with the user groups, users, principals, and other concepts that exist in the target enterprise’s operational environment.The security roles and information are configured and mapped in configuration files and deployment descriptors, as discussed in the following slides.



JAAS Provider Types in OC4J

The JAAS provider in Oracle Application Server 10gContainers for J2EE (OC4J) supports two provider types:• The LDAP-based provider type that is used to

access an Oracle Internet Directory (OID) repository

• The XML-based provider type that is used to access an XML file repository by using:– The jazn-data.xml file – The principals.xml file

The repositories store the realm (users and roles) and the policy (permissions) information.

JAAS Provider ServicesThe JAAS provider supports two types of repository providers (referred to as provider types):

• LDAP-based provider type: Used to access an OID repository• XML-based provider type: Used with an XML file–based repository, typically

jazn-data.xml, or via principals.xmlOID and jazn-data.xml are repositories that are used to store the realm (users and roles) and the policy (permissions) information. This course discusses configuring security with an XML repository file by using the jazn-data.xml file.The OC4J container uses jazn-data.xml as the default security provider because:

• Passwords are encrypted (They are not encrypted in principals.xml.)• A <role> element represents a group comprising users and other roles. The

principals.xml file uses a <group> element that does not allow another group to be part of it, and associates a principal with multiple groups in the <user>element.

• You can use JAAS Role Based Access Control (RBAC), including role hierarchies, direct assignment of permissions to a role, and activation of permissions for the role

• Full support for the Java 2 Permission Model is implemented



Configuring Security

• Define users and groups in jazn-data.xml (or principals.xml).

• Define security view or logical roles in J2EE deployment descriptor (web.xml or ejb-jar.xml).

• Map logical roles to users and groups in OC4J-specific deployment descriptor (orion-web.xmlor orion-ejb-jar.xml).

• Provide a user or group with read and write access to the Java Naming and Directory Interface(JNDI) namespace in application.xml (or application-specific orion-application.xml).

Configuring SecurityThe configuration of the security environment involves:

• Defining users and groups in a configuration file, that is, in the jazn-data.xml (or principals.xml) file

• Defining logical roles in the J2EE application deployment descriptor• Mapping the logical roles to users and groups in the Oracle-specific deployment

descriptor The other methods of authorization and authentication include the LDAP-based OID and the use of single sign-on features of the Oracle Application Server 10g architecture. You can use the JAAS API to build custom providers. The jazn-data.xml file is used in the course examples and labs because it is the default provider and it is easy to configure.To allow a client access to the JNDI namespace, the OC4J application.xml file must be modified by adding a user or group element in a <security-role-mapping>element. For example, allow read access to the JNDI namespace for the administrators group:

<namespace-access><read-access><namespace-resource root=""><security-role-mapping><group name="administrators" /></security-role-mapping>

</namespace-resource></read-access> ... </namespace-access>



Defining the Users, Groups, and Roles

• The identities (users and groups) are known to the container by using the jazn-data.xml.

• The identities can be specific to an application.<jazn-realm><realm><name>jazn.com</name><users><user><name>admin</name><display-name>OC4J Administrator</display-name><description>OC4J Administrator</description> <credentials>{903}5NwtZOAJa2Ty7Ksbmu3IUOfK9PgK/Kxi</credentials></user><user><name>user</name><description>The default user</description><credentials>{903}/pQcVBQ6+AN+NNF2MzYb/0+gR4lOVwwh</credentials></user> ...

Defining the Users, Groups, and RolesA realm provides access to users and roles (groups) and optionally provides administrative functionality. The users and groups are identities that are known by the container. Roles are the logical identities that each application uses to indicate access rights to different objects. Security credentials can be defined at:

• A global application level: Users and groups can be shared by all the deployed applications if they are defined in the global jazn-data.xml file located in the ORACLEAS_HOME/j2ee/home/config directory.

• A specific application level: Users and groups may be defined for a particular application by being listed in the application-specific jazn-data.xml file, which is identified in the orion-application.xml file for that application.

The <users> element defines one or more users. Each user is specified in a <user>element. A user may be associated with a role that is defined in the file. The example, (jazn-data.xml file) in the slide above shows how to define a realm, called jazn.com, containing the users admin and user. Observe that passwords are encrypted.Each <role> element defined in the <roles> element identifies the group name and provides a <members> element to specify the users belonging to the group (or role). A member element can contain another role name; that is, roles can be hierarchical (see the example in the following slide).

Defining the Users, Groups, and Roles (continued)Example of jazn-data.xml:

<jazn-realm><realm><name>jazn.com</name><users> ...</users><roles>

<role><name>administrators</name><display-name>Realm Admin Role</display-name><description>Admin role for realm.</description><members>

<member><type>user</type><name>admin</name>

</member></members>

</role><role>

<name>users</name><members>

<member><type>user</type><name>user</name>

</member><member><type>role</type> 

<name>administrators</name></member>

</members></role>

</roles>...

</realm></jazn-realm> ...

Note: In this sample XML file, the <member> element whose <type> is role shows how one role (in this case administrators) can belong to another role, that is, the users role. This is the implementation of a role-based hierarchical structure.



Managing Users and Groupswith the JAZN Admintool

The JAZN Admintool can manage users, roles, and groups and can assign roles to users in XML or LDAP-based data. • It modifies jazn-data.xml or the LDAP

repository.• It prompts for admin username and password.

Examples:• Adding a user:

• Adding a role (or a group):

• Granting a role to a user (assign user to a group):

java –jar jazn.jar –adduser jazn.com ora1 oracle

java –jar jazn.jar –addrole jazn.com managers

java –jar jazn.jar –grantrole manager jazn.com ora1

Managing Users and Groups with the JAZN AdmintoolThe JAZN Admintool can be used to manage both XML and LDAP-based JAAS data from the command-line prompt. It is a Java application in the jazn.jar file that is located in the Oracle Containers for Java (OC4J) home directory. To run the Admintool, ensure that the following lines are added to your Java Runtime Environment java.security file (Note: This file is located in the JRE_HOME/lib/security directory):

auth.policy.provider=oracle.security.jazn.spi.PolicyProviderlogin.configuration.provider=\

oracle.security.jazn.spi.LoginConfigProvider

To run the Admintool, open a Console window and change the directory to the OC4J home directory, for example, JDEV_HOME\j2ee\home. You can enter the following command for help: java –jar jazn.jar –helpThe help command does not prompt for a username or a password.The first example on the slide shows how to add a user to a realm. The first parameter after the –adduser option is the realm name (jazn.com is the default) followed by the username and password. The password is encrypted in the XML file.Note: The Enterprise Manager Web interface of Oracle Application Server 10g can also manage J2EE security.


Managing Users and Groups with the JAZN Admintool (continued)The second example in the preceding slide shows how to create a role. Roles are also added to a realm. The –addrole option is followed by the realm name and then the role name, which in this case is managers.The third example in the slide assigns the role of managers to the user ora1 in the jazn.com realm. This assigns the user to a role (group).Each time you execute the command-line tool, you are prompted for a username and password. The username and password must be a valid combination that is found in the jazn-data.xml file. However, for administrative tasks (such as creating new users), the user must be privileged, such as the OC4J admin user. The following is an example of using the tool to list realms:

prompt> java -jar jazn.jar –listrealmsRealmLoginModule username: adminRealmLoginModule password:********jazn.com

The result text is: jazn.com. The JAZN Admintool has several command-line options. Some of the useful options are:Listing the realms:

java –jar jazn.jar -listrealms

Listing all the users in a realm:java –jar jazn.jar –listuser jazn.com

Listing all the roles in a realm:java –jar jazn.jar –listroles jazn.com

Listing users assigned to the users role in a realm:java –jar jazn.jar –listusers jazn.com –role users

Creating a role hierarchy by granting a role to another role in a realm:java –jar jazn.jar –grantrole users jazn.com –role manager

Note: This adds the managers role as a member of the users role.If you intend to execute multiple commands with the JAZN Admintool in one session, then it is recommended that you invoke the command shell feature of the JAZN Admintool. In this way, you need to log in only once for the shell session. To start a JAZN Admintool shell session, use the following command:

java –jar jazn.jar –shellRealmLoginModule username: adminRealmLoginModule password:********JAZN:> listusersjazn.com/user...JAZN:> adduser jazn.com ora1 oracleJAZN:> exit

For more information about JAZN Admintool, refer to Oracle Application Server 10g Containers for Java: Service Guide.



Defining the Logical Roles

The logical security roles defined in the J2EE deployment descriptors are:• Specified in the web.xml file for Web applications,

or in the ejb-jar.xml file for EJB components.• Defined in the <security-role> element for the

application. One or more roles can be specified.• Authorized to invoke methods that are listed in the

<method-permissions> element for the security role.

• Scoped at the level of the application orall the enterprise beans in the jar file.

Defining the Logical Roles The roles are logical identities that each application uses to indicate access rights to its different objects. The Web application (web.xml) and EJB deployment descriptor (ejb-jar.xml) identify roles that are needed to access different URLs or methods of the application. In the J2EE deployment descriptors, security roles are defined in the <security-role>element that is located in the <assembly-descriptor> element. Because the application assembler provides the (logical) security view of the application, the deployer’s job is simplified.The application assembler defines one or more security roles in the deployment descriptor and then assigns URL patterns or groups of methods of an enterprise bean to the security roles.Because the application assembler generally does not know the security environment of the operational environment, the security roles are meant to be logical roles (or actors), each representing a type of user that should have the same access rights to the application. The application deployer can then map the logical roles to the security definitions in the execution environment of the application.

Defining and Using Logical Roles in Web Applications (web.xml)

• Define logical role in the <security-role>element

• Use role in <security-constraint> element<security-role><role-name>hr_managers</role-name> 

</security-role><security-constraint> <web-resource-collection><web-resource-name>UpdEmployee</web-resource-

name><url-pattern>/UpdEmployees.jsp</url-pattern></web-resource-collection><auth-constraint><role-name>hr_managers</role-name> 

</auth-constraint><user-data-constraint><transport-guarantee>NONE</transport-guarantee></user-data-constraint></security-constraint>

Defining and Using Logical Roles in Web ApplicationsThe example in the slide shows how to define a logical security role, named hr_managers, that is to be used by the Web application. Each logical role is defined in the <security-role> element, and many security role elements can be defined. The logical role is applied to a URL pattern that is contained in a <security-constraint> element. The elements that nest in the <security-constraint>definition are as follows:

• The <web-resource-collection> element contains a <web-resource-name> that contains one or more <url-pattern> elements.

• The <web-resource-name> element is the name of the Web application.• The <url-pattern> element defines the URL pattern for Web application pages.• The <auth-constraint> element gives access to users in the logical role to the

collection of URLs that are identified in the enclosing security constraint.• The <user-data-constraint> element indicates whether the data that is

communicated between the client and the container is protected or not.


Defining and Using Logical Roles in Web Applications (continued)Note: By default, all users have access to the URLs that are provided in the Web applications, unless you control the access by using the mechanisms that are shown in the slide. The J2EE applications can obtain the username and password from the OC4J container or Web application server, which can be configured to obtain the credentials from HTML form fields, basic or digest authentication mechanisms, or Oracle Single Sign-On services.



Defining and Using Logical Roles in EJBs (ejb-jar.xml)

• Define logical role in <security-role> element.• Assign access in <method-permission> element.<assembly-descriptor><security-role><description>HR Manager</description><role-name>hr_managers</role-name></security-role><method-permission><role-name>hr_managers</role-name><method><ejb-name>HrApp</ejb-name><method-name>incrementSalary</method-name><method-params><method-param>int</method-param><method-param>int</method-param></method-params>

</method></method-permission> ...<assembly-descriptor> ...

Defining and Using Logical Roles in EJBs (ejb-jar.xml)The code in the slide shows the process of specifying the security roles and method permissions on different beans and their methods. All these details are specified in the <assembly-descriptor> element of the XML deployment descriptor.You can specify many security roles with the <security-role> element. The example in the slide shows hr_managers being specified as a role name. The <method-permission> element specifies the role name (from the security role specified above), bean, and its method names for which this role is authenticated. The method permissions are defined for the method that is named in the <method-name>element. The name of a method can be specified as:

• An asterisk (*) representing all methods in the component• A specific individual method name in the component, including its parameters

Note: By default, if OC4J generates the EJB deployment descriptor, then it prevents access for all users to methods of the EJB, unless the access is explicitly specified. However, JDeveloper generates an OC4J deployment descriptor that allows the calling user access to all the methods of an EJB. The example in the slide assumes that all the users have been granted access to all the methods of the HrApp bean, except the incrementSalary()method, which can be executed only by users belonging to the hr_managers role.



Mapping Logical Roles to Users and Groups

Mapping is done in the OC4J deployment descriptors.• A logical role to a group:

• A logical role to a user:

• A logical role to a group or a specific user:

<security-role-mapping name = "hr_managers"><group name="managers"/>

</security-role-mapping>

<security-role-mapping name = "hr_managers"><user name="ora1"/>


<security-role-mapping name = "hr_managers"><group name="managers"/><user name="ora1"/>


Mapping Logical Roles to Users and GroupsThe mapping of the logical security roles, defined in the J2EE deployment descriptors, is done by using the OC4J-specific deployment descriptor files. Define mapping in:• orion-web.xml for Web applications• orion-ejb-jar.xml for EJB components• orion-application.xml for either the Web applications or the EJB components

The logical roles are mapped to the actual users or roles (groups) defined in the security provider that is configured for the J2EE environment (for example, the jazn-data.xmlfile). The slide shows examples of mapping a logical role to a group, to a specific user, or to a combination of users and groups. For example, method access is given to all the users in the managers group:

<security-role-mapping name="hr_managers" impliesAll="true" ><group name="managers" />


The impliesAll attribute that is set to true includes all the users with the hr_managers role that are mapped as managers in the J2EE environment.To define the default access permissions for all methods in an EJB component, you define the security role mappings in the <default-method-access> element.



Programmatic Access to a Caller’s Security Context

• Not all security policies can be expressed declaratively.

• Use a programmatic interface to access the security context of the calling client from the bean methods.

• To access the security information of the caller, the javax.ejb.EJBContext interface defines the following two methods:

java.security.Principal getCallerPrincipal();

boolean isCallerInRole(java.lang.String roleName);

Programmatic Access to a Caller’s Security Context Sometimes a bean code may have special requirements or may need to know the security principal or the role name of the user that is calling methods on the bean. Such a requirement may arise because of the need to perform some special operations of logic for certain user roles or principals. The EJB architecture provides access to the security context of the clients for these purposes. The interface used is the EJBContext:

public interface javax.ejb.EJBContext {...java.security.Principal getCallerPrincipal();boolean isCallerInRole(java.lang.String roleName);...

}

The getCallerPrincipal() method is used to obtain the Principal object representing the client that is currently accessing the bean. The Principal object can then be used to track the identity of the clients that are making updates to the specified bean.The isCallerInRole() method tells you whether the client accessing the bean is a member of a specific role, identified by a role name. This method is useful when more access control is needed than the simple method-based access control can provide. This method allows fine-grained programmatic access control to the methods of a bean.



Client Authentication

• For Web applications:– Use Web application server security mechanisms,

where credentials are passed through to the J2EE environment

– Use OC4J container Web securityExamples: Basic or Digest Authentication, HTML form fields, and Client SSL certificates

• For EJB components:– Stand-alone (remote) clients define credentials in

InitialContext, and the jndi.properties file or settings in a Hashtable.

– Local clients, such as servlets, JSPs, or other EJBs, pass their credentials by using the Context object.

Client Authentication The authentication of Web clients can be managed by using Oracle Application Server 10gHTTP Server capabilities, such as basic or digest authentication, HTML form fields, or Single Sign-On services managed by an LDAP-based service, such as Oracle Internet Directory (OID).Alternatively, you can use similar services from within the OC4J container. For example, you can enable basic authentication for a J2EE Web application by adding the following <login-config> element details to the Web application deployment descriptor (web.xml):

<login-config><auth-method>BASIC</auth-method>

</login-config>

The container then requests a username and password from the Web browser.When you access EJBs in a remote container, you must pass valid credentials to this container.

• Stand-alone clients define their credentials in initial context. The credentials can then be initialized by using the jndi.properties file deployed with the Enterprise Archive (EAR) file, or the Hashtable.

• Servlets or JavaBeans running within the container pass their credentials in the InitialContext, which is created to look up the remote EJBs.



EJB Client Authentication with the jndi.properties file

• In the jndi.properties file:

• Client accessing the EJB with the above JNDI properties:

java.naming.security.principal=ora1

java.naming.security.credentials=welcome

java.naming.factory.initial=com.evermind.server.\ApplicationClientInitialContextFactory

java.naming.provider.url=ormi://localhost/hrApp

Context ic = new InitialContext();

EmployeeHome = (EmployeeHome) ic.lookup(

"java:comp/env/Employee");

EJB Client Authentication with the jndi.properties fileThe client can authenticate by using the JNDI properties defined and deployed with the EJB. The example in the slide shows the jndi.properties file that contains the security principal and credential details defined for the Employee EJB. The client uses the Context object obtained by creating the initial context and performs a look up for the Employee EJB.The JNDI properties file contains a list of key/value pairs. The key is the name of the property (for example, java.naming.factory.initial), and the value is a string in the format defined for that property. The use of this file to specify any JNDI environment properties allows the JNDI to be configured with minimal programmatic setup.Setting the JNDI properties is discussed in the lesson titled “Communicating in J2EE.”Note: The trailing backslash in the line containing the java.naming.factory.initial value is a standard continuation character used in Java property files to allow a value to continue over more than one line.



EJB Client Authentication with a Hashtable

Hashtable env = new Hashtable();

env.put("java.naming.provider.url",

"ormi://localhost/hrApp");

env.put("java.naming.factory.initial",

"com.evermind.server." +

"ApplicationClientInitialContextFactory");

env.put(Context.SECURITY_PRINCIPAL, "ora1");

env.put(Context.SECURITY_CREDENTIALS, "welcome");

Context ic = new InitialContext (env);

EmployeeHome = (EmployeeHome) ic.lookup(

"java:comp/env/Employee");

Client Authentication: InitialContextTo access remote EJBs from a local client such as a servlet, another EJB, or a Java ServerPage, the client passes the credentials in the InitialContext object, as shown in the slide.A client needs to specify the following attribute values to authenticate itself with the server:

• The user ID (Context.SECURITY_PRINCIPAL)• The password (Context.SECURITY_CREDENTIALS)

The client sets these property values in a Hashtable that is used to get the JNDI InitialContext. Note: Setting the client authorization by using the JNDI properties and the InitialContext object is discussed in lesson 10 of this course.



Setting Access Control with JDeveloper

• You can set security roles to access a Web application or an EJB by using JDeveloper deployment descriptor editors:– Use the Web Application Deployment Descriptor

editor for Web applications.– Use the EJB Module Editor for EJBs.

• For Web applications, set the access permissions as constraints defining URL patterns for a Web resource.

• For EJBs, set the access permissions for either individual methods or all the methods of the bean.

Setting Access Control with JDeveloperYou can create security roles for Web applications or EJB modules by using:

• The Web Application Deployment Descriptor editor for Web applications• The EJB Module Editor for EJBs

The Web Application Deployment Descriptor editor is displayed by right-clicking the web.xml file and choosing the Settings menu option. You define the logical security role in the Security section, and define access rules for the logical roles for a Web resource and URL patterns in the Constraints section.The EJB Module Editor is displayed by right-clicking the ejb-jar.xml file and selecting the Edit EJB Module menu option. In the EJB Module Editor, access the Security Role section to create security roles and associate them with method permissions.The slides that follow show how to use the EJB Module Editor.



Creating Web Application Security Roles

1. Right-click web.xml, select Properties.2. In the Security Roles section, click Add.

Creating Web Application Security RolesUsers and roles (groups) are stored in the jazn-data.xml file, if the JAAS security has been configured to use the OC4J jazn-data.xml file. To declaratively create security for your Web application, you first define one or more roles to be available to the application. The security role names can be:

• A role name defined in jazn-data.xml• Any logical role name of your choice

If you define a logical name, you must map it to actual users or roles found in the jazn-data.xml file. The mapping is done by using a <security-role-mapping> element in the OC4J deployment descriptor (orion-web.xml).The slide shows how to create a logical role called hr_managers. The dotted arrow indicates that the role will be added to the list of roles available for authentication and authorization rules in this Web application.



Web Application Login Authentication

Typically done using Oracle HTTP Server using either Basic, Digest, Login Form, Single-Sign On, and so on.

Web Application Login AuthenticationThe Oracle Application Server 10g HTTP Server is a Web server that is typically used to manage authentication. The server provides you with a choice of techniques for authenticating users, including the following:

• Basic authentication, where the browser prompts for a username and a password. This is not secure and is often combined with Secure Socket Layer (SSL).

• Digest authentication, where the browser prompts for a username and password, which is more strongly encrypted than basic authentication. This lacks browser support.

• Form-based authentication, requiring an application to generate a HTML form to submit the username and the password. A J2EE container can authenticate the username and password that is submitted by using an HTML form if the form actionattribute is set to the string j_security_check, and the username and password fields are named j_username and j_password, respectively. Note: Oracle Application Server 10g Single Sign-On can be enabled to provide a login form and do the authentication by using an LDAP-based service such as OID.

• Client certificate authentication, requiring that the browser use HTTPS and have a personal certificate installed

Note: The slide shows how to enable basic authentication for the current Web application by using the OC4J container.



Web Application Authorization

• Define a Web resource (URLs and HTTP methods).• Grant security roles access to the Web resource.

Web Application AuthorizationAfter the user is authenticated, you apply authorization by granting permissions to a user or role. You need to create or modify the <security-constraint> element in the web.xml file to declaratively implement Web application authorization in a J2EE security environment. The <security-constraint> element contains:

• A Web resource definition in a <web-resource-collection> element• An authorization part in the <auth-constraint> element allowing the security

role defined for the application to use the Web resourceA Web resource is given a user-defined name, contains a collection of one or more URL patterns, and is optionally combined with HTTP methods. This gives a single name for a collection of Web pages and types of HTTP requests that can be made for those pages.The authorization constraint restricts access to a set of security roles that are assigned to the Web resource. The security roles must be defined or mapped to an actual role using the deployment descriptors.The slide shows how to create a Web resource called GetEmployee, with a single URL pattern /GetEmployees.jsp, related to the application root context. The authorization for the GetEmployee Web resource allows all users who have the managers or staffrole access to the Web page. By default, all users have access to a Web resource.



Creating EJB Security Roles

1. Select the Security Roles section.2. Click Add to create and enter a new logical role

name and description in the Create Security Role dialog window.

Creating EJB Security Roles Create users and groups in the jazn-data.xml file. Then, define the logical security roles in the ejb-jar.xml file. This later step can be achieved by using the JDeveloper wizards, as follows:

1. Select the Security Roles section. 2. Click Add to create a new security role (you can delete existing logical security roles

by using the Delete button). Enter a new role name and description in the Create Security Role window. In the example, a role hr_managers is created.

The information specified here is included in the deployment descriptor of the EJB.



Setting Method Permissions

In the Method Permissions section, select the roles and the methods that are accessible for those roles.

Setting Method PermissionsWith this step, you can set different access permissions for different roles on the methods of the bean. All the information specified here is included in the deployment descriptor of the EJB.

• Select the Method Permissions section. Click Add to add method permissions. (You can click Remove to delete selected permissions.)

• The existing roles are listed in the Available Security Role Names section. Shuttle the role to the Chosen Security Role Names section to specify method permissions for the role.

• Click Add Method to create method permissions. Select one or more methods in the list to grant permissions on them to the selected roles. Permissions to all methods is indicated by *. The slide shows the role, hr_managers, being granted access to the incrementSalary(int x,int y) method of the HrApp bean.

• Deploy the bean with new settings. Any role other than the one specified in the deployment profile will not be able to access the bean methods. If a role is given permission to access only specific bean methods, then the client accessing the bean in that role will have access permissions only to those methods of the bean.



Method Access in EJB Deployment Descriptors

• The example shows the hr_managers role granted access to the incrementSalary() method.

• Explicit settings have precedence over default method access in the OC4J deployment descriptor.

Method Access Settings in the EJB Deployment DescriptorThe slide shows an example of an EJB deployment descriptor (ejb-jar.xml) as created in the JDeveloper, allowing users with the hr_manager role access permissions to the incrementSalary() method of the bean. Depending on the settings in the <default-method-access> element in this descriptor (not shown in the slide), the users with the hr_manager role may or may not be allowed access to other methods in the HrApp bean. If a user calling the incrementSalary() method is not assigned to the hr_managers role, then that user is denied access to the method.Default method access is specified in the OC4J-specific deployment descriptor (orion-ejb-jar.xml) for the EJB. By default, JDeveloper generates the following default method access setting for EJBs, allowing all authenticated users access to the bean methods:

<default-method-access><security-role-mapping impliesAll="true"

name="<default-ejb-caller-role>"/></default-method-access>

Note: Explicit method access settings in the J2EE deployment descriptor (ejb-jar.xml) have precedence over the specified default method access settings.



Creating a Mapping for the Logical Roles

In JDeveloper, edit the orion-ejb-jar.xml file.1. Right-click the file and select Properties.2. Select Security Role Mapping, and then click Add.

3. Enter a logical role name (e.g., hr_managers).

Mapping the Logical Role to a JAZN IdentityFor the security settings to be effective, you must map the logical role that has been assigned method permissions to the identities of a real user or group.The example in the slide modifies the OC4J EJB deployment descriptor to map the logical role hr_managers from the HrApp session bean to a real identity (a group, a user, or a combination of each) existing in the XML JAZN jazn-data.xml file.The slide shows the creation of the role name to be mapped. The next slide completes the mapping by assigning the managers group in the jazn-data.xml file to the logical role.



Mapping JAZN Identities to a Logical Role

Mapping JAZN Identities to a Logical Role in JDeveloperThe slide shows the screenshots indicating the key steps required to map the logical role hr_managers to the managers group, which is defined in the jazn-data.xml file.The steps are:

1. Right-click orion-ejb-jar.xml to open the OCJ4 EJB Deployment Descriptor window, and then select the Settings option.

2. Select the Security Role Mapping entry.3. Select the hr_managers logical role (added as shown in the previous slide).4. Click the Details button to display the Details for “hr_managers”

window.5. Click the Groups tab, and then click the Add button to add the managers group.

(You can also add users by using the Users tab.)6. Click OK to close the Add Group window.7. Click OK to close the Details for ‘hr_managers’ window.8. Click OK to close the OC4J EJB Deployment Descriptor window.

View the orion-ejb-jar.xml file to check the results of this mapping procedure.



Mapping JAZN Identities to a Logical Role

Mapping JAZN Identities to a Logical Role in JDeveloper (continued)The slide shows the screenshots indicating the key steps required to map the logical role hr_managers to the managers group, which is defined in the jazn-data.xml file.The steps are:

1. Right-click orion-ejb-jar.xml to open the OCJ4 EJB Deployment Descriptor window, and then select the Properties option.

2. Select the Security Role Mapping entry.3. Select the hr_managers logical role (added as shown in the previous slide).4. Click the Groups tab, and then click the Add button to add the managers group.

(You can also add users by using the Users tab.)5. Click OK to close the Group window.6. Click OK to close the OC4J EJB Deployment Descriptor window.

View the orion-ejb-jar.xml file to check the results of this mapping procedure.



Mapping Results in orion-ejb-jar.xml

The OC4J XML Deployment Descriptor holds the details for mapping the logical role to the allowed identities (groups or users).For example:

Mapping Results in orion-ejb-jar.xmlThe slide shows the results after the logical role hr_managers is assigned to the managers group.The <security-role-mapping> element is added with the name attribute set to the logical role hr_managers. One or more groups or user elements can be nested in the <security-role-mapping> element. The slide shows an entry for the managersgroup.



Accessing the EJB with New Permissions

• Any client with a role other than those specified in the deployment descriptor receives the exception com.evermind.server.rmi.OrionRemoteException.

• Clients without read/write access to the namespace receive the exception javax.naming.NoPermission.

Accessing the EJB with New PermissionsA client application invoking EJB methods as a user without the role specified in the EJB deployment descriptor receives the exception com.evermind.server.rmi.OrionRemoteException.Clients that do not have read/write access granted to the JNDI namespace receive the javax.naming.NoPermission exception when attempting to look up the JNDI name of the published EJB. Read/write access to the JNDI namespace is specified in the <namespace-access> element of the OC4J default application.xml file, or the application’s own OC4J-specific application.xml file.



Summary

In this lesson, you should have learned how to:• Use the J2EE security architecture to remove from

the developer the burden of implementing security• Define Web applications and EJB security

mechanisms such as security roles• Define users, groups, and logical roles; map the

logical and concrete roles for client authorization• Access security information of the caller by using

methods in the javax.ejb.EJBContext interface• Authenticate EJB client applications by using the

jndi.properties file and InitialContext




This practice covers the following topics:• Using the Web Application Deployment Descriptor

to create logical security roles for a Web application

• Enabling basic authentication in an OC4J container

• Programmatically determining the user credentials and using it to control access to information

• Using EJB security to control access to methods in a bean

Practice 20-1: OverviewIn this practice, you edit the EJB module to change the security settings. You give one user account access to the bean, and you then try to access it from another account to see the effect of the security settings.


Practice 20-1In this practice, you are provided with most of the application code. The goal of this practice is to use J2EE declarative security mechanisms to protect access to different parts of the application. You use programmatic techniques to limit the information about an employee’s salary displayed to the application user (depending on the role of the user).Note: The application in this practice originates from the practice in lesson 17.Understanding the ApplicationOpen the practice20.jws workspace in the practice20 directory. There are two projects:

• The secure project, containing the files you will modify• The securesoln project, containing the solutions for this practice

Expand the secure project, and take approximately two minutes to examine the content of the following files used to configure the application security credentials:

• The orion-application.xml file is an OC4J application–specific deployment descriptor that identifies the location of the application-specific user and group data in the jazn-data.xml file. It also grants read access to the namespace to the staffrole.

• The jazn-data.xml file contains all the users and roles for this application. This file was created using the JAZN Admintool provided with OC4J, where each username is derived from the EMAIL column of the EMPLOYEES table, and their passwords are all set to oracle. This file defines two roles:

- The managers role, which is granted to only those employees in the database who have the following job IDs: AD_PRES, AD_VP, HR_REP, FI_MAN

- The staff role, which is granted to all other employees. The managers role has been added as a member of the staff role, because all managers are also staff.

The application provides a default index.html page that is not protected, allowing users to access a common welcome page. The only hypertext link on the index page leads to the GetEmployee.jsp page, which must be password protected.The user should log in using a valid name and the password oracle. The GetEmployee.jsp uses an entity bean to retrieve information about that employee, and presents a page that allows users to add new employees or to query employees by department. When employees are queried, the user is able to update or delete the employee record.Your task is to declaratively allow only managers to create and delete employees and update employee salaries. This is achieved through a combination of using Web and EJB authorization techniques covered in this lesson.Practice Steps

1. Deploy the application to observe the default behavior.a. Compile the secure project, and then right-click EmployeesWeb.deploy

and deploy the application to your OracleAS10g connection. EmployeesWeb.deploy has a profile dependency on EmployeesEJB.deploy to ensure that the EJB is deployed as part of the enterprise application.


Practice 20-1 (continued)b. Enter the following URL: http://localhost/secure.

Note: You will find that the application has no login mechanism, and defaults to a user called JCHEN, who can perform all tasks.

2. Create Web application security roles by using the actual role names defined in the jazn-data.xml file.

a. In the secure project, right-click web.xml and select the Properties menu option to display the Web Application Deployment Descriptor editor.

b. Click the Security Roles section, and then click the Add button to create security roles for managers and staff.

c. Select the Preview XML section to examine the <security-role> elements added to the web.xml file.

Note: Do not close the Web Application Deployment Descriptor editor window.3. Enable basic authentication to be used by the OC4J container.

a. Click Login Configuration and click the HTTP Basic Authentication option button, and enter Employee Application in the Realm field.

b. Select the Preview XML section to examine the <login-config> element added to the web.xml file.Note: Do not close the Web Application Deployment Descriptor editor window.

4. Create two security constraints for the application by defining two Web resources and their associated URL patterns and appropriate role authorizations.

a. Select the Security Constraints section and click the New button. Click the Add button to create a constraint with the Web resource name GetEmployee.

b. Select the GetEmployee Web resource name that you created in the previous step, and in the URL Patterns tabbed page add the following URL:/GetEmployee.jsp.

c. Click the Authorization tab and select the check boxes next to the managersand the staff roles. The managers role must be selected, otherwise, the J2EE container does not recognize a user with the managers role, but only their staff role.

d. Select the Security Constraints section and click the New button. Click the Add button to create a second security constraint with the Web resource name MaintainEmployee.

e. Select the MaintainEmployee Web resource name, and add the following URL patterns: /Add* and /Delete*. In the Authorization tabbed page for this second constraint, select only the check box next to the managers role.

f. Select the Preview XML section to examine the two <security-constraint> elements added to the web.xml file.

g. Click the OK button to close the Web Application Deployment Descriptor editor window.

5. Redeploy the application by using the EmployeesWeb.deploy file to your OracleAS10g application server connection. Before you run the application, close all Web browser windows. Then start the Web browser and enter the following URL: http://localhost/secure.


Practice 20-1 (continued)6. Click the Get Employees hypertext link to start the application. You should be

prompted for a username and password in a dialog box, which has the Realm name of Employee Application. Test your application behavior with two different usernames. Use one user as a staff member only, and the other as a manager.Hint: The following users are staff members only: jchen, ngreenbe, pfay, and jwhalen. The following users are managers: ldehaan, sking, nkochhar, and smavris. All users have the password oracle. Alternatively, check the jazn-data.xml file in your project for other names with the staff and managers role.

7. At this stage, all users are able to update other employees’ salaries. You now modify the EJB to allow only those users with the managers role to update an employee’s salary.

a. In the secure project, right-click ejb-jar.xml and select Properties.b. In the EJB Module Editor, select the Security Roles node and click the Add

button to create the managers security role entry.c. Select the Preview XML section to observe the <security-role> element

added in the <assembly-descriptor> element.d. Click Method Permissions and click the Add button to create a method

permission.e. In the Create Method Permission window, shuttle the managers role to the

Chosen Security Role Names area, and select the void setSalary(Long newSalary) entry from the list in the Methods area. Then click the OK button.

f. Select Preview XML and observe the <method-permission> element added inside the <assembly-descriptor> element of the bean.

g. Click the OK button to close the EJB Module Editor and apply the changes you have made.

8. Redeploy the application with EmployeesWeb.deploy to your OracleAS10gapplication server connection. Close all your Web browser windows. Then start the Web browser and enter the following URL: http://localhost/secure and test the modification of an employee’s salary as a user using the managers role and as a user with the staff role. Hint: Close the browser between login sessions.

Practice 20-1 (continued)Optionally, if you have time, then you can perform the following:

9. Programmatically access and display authentication information for the users after they log in.

a. Open the GetEmployee.jsp file in the Code Editor, and locate the following HTML tags:<hr><h3>Security Information</h3><hr>

Replace the HTML comment line <!– Enter code here … --> with output that resembles the following four lines of information, each with a JSP expression after the word shown:<b>Principal:</b> <%= … %><br><b>Staff:</b> <%= … %><br><b>Manager:</b> <%= … %><br><b>User :</b> <%= … %><br>

b. In the JSP expression for Principal, display the string information about the java.security.Principal object. Hint: Use request.getUserPrincipal().

c. In the JSP expression for Staff, display true if the user making the request is a member of the staff role; otherwise display false.Hint: Use request.isUserInRole(...).

d. In the JSP expression for Manager, display true if the user making the request is a member of the managers role; otherwise display false. Hint: Use request.isUserInRole(...).

e. In the JSP expression for the User information, display the remote username. Hint: Use request.getRemoteUser().

f. Compile the GetEmployee.jsp file to eliminate syntax errors.10. Programmatically prevent the current user from seeing another employee’s salary

when obtaining the result list after finding employees by department ID.a. Edit GetEmployeeByDept.jsp in the Code Editor.b. Search for the following JSP code: <td><%= emp.getSalary()

%></td> in the file and modify this line to display the salary as a string if the current user has the managers role. Otherwise, display the string n/a (“not available”).

c. Compile the GetEmployeeByDept.jsp file to eliminate syntax errors.11. Finally, deploy the EmployeesWeb.deploy application profile to the

OracleAS10g connection. Test the application changes starting with the following URL: http://localhost/secure. Hint: Close the browser windows between the staff and managers user login sessions.


Oracle Application Server 10g Transaction Support



Objectives

After completing this lesson, you should be able to do the following:• Identify the use of bean-managed transactions

(BMT)• Identify the use of container-managed

transactions (CMT)• Describe how Oracle Application Server 10g

Containers for J2EE (OC4J) supports one-phase and two-phase transaction protocols

ObjectivesJava 2, Enterprise Edition (J2EE) containers provide a transaction service. Enterprise JavaBeans use Java Transaction API (JTA) 1.0.1 for managing transactions. This lesson discusses the method for using JTA in OC4J.



What Is a Transaction?

A transaction:• Is a single logical unit of work or a set of tasks

that are executed together• May access one or more shared resources, such

as databases• Must be atomic, consistent, isolated, and durable

(ACID)

OverviewTransactions manage changes to multiple databases in a single application as a unit of work.. A transaction must be:

• Atomic: A transaction must execute completely or not execute at all. For example, in an account transfer transaction, both debit and credit must be successful as a unit, or both must fail.

• Consistent: This refers to the integrity of the underlying database. In an account transfer example, the amount of debit to one account must equal the credit to the other account.

• Isolated: The steps during a transaction cannot be affected by or be visible to any other part of the system until the transaction is complete.

• Durable: All data changes that are made during a transaction must be written to some physical storage before the transaction is successfully completed, so that even if the system crashes, the changes are not lost.



Enterprise JavaBeans (EJB) Supportfor Transactions

• The EJB architecture supports declarative and programmatic transactions.

• The bean provider is not exposed to the complexity of distributed transactions.

• The EJB container provides a transaction infrastructure.

• EJBs do not support a nested transaction model.

Enterprise JavaBeans (EJB) Support for TransactionsThe EJB architecture supports declarative and programmatic transactions. In CMT, you declare the transaction attributes in the deployment descriptor. A container uses these values for maintaining transactions in the beans. In BMT, you code the logic in the bean class to manage the transactions.An Enterprise JavaBean is required by the specification to support flat transactions but is not required to support nested transactions. This means that the container and the server must provide a transaction service to the EJB components and must also provide some standard interfaces into this service. You see in the next few slides the mandatory interfaces that must be supported by the server provider, so that the bean developer does not have to worry about the low-level details of the transaction infrastructure.



EJB Transaction Model

• Demarcating a transaction determines:– Who begins and ends a transaction– When each of these steps occur

• A bean-managed (explicit) transaction:– Is demarcated by the bean– Is specified programmatically in the bean through

JTA interface or Java Database Connectivity (JDBC) interface

• A container-managed (declarative) transaction:– Is demarcated by the container – Is specified declaratively (implicit) through the XML

deployment descriptor

EJB Transaction ModelDemarcating transactions refers to defining the transaction boundaries, that is, who starts and stops the transaction, and when each occurs. A transaction may involve more than one source and destination, and may span across multiple client and server objects.EJB transactions can be demarcated as BMT or CMT. The bean provider uses the EJB deployment descriptor to specify a value of a Bean or Container in the <transaction-type> element to define the type of transaction demarcation implemented.In the BMT model, the EJB client or the bean programmatically demarcates the transaction by executing the appropriate begin or commit/rollback methods by using Oracle’s implementation of the JTA specified by Sun Microsystems. Oracle’s JTA implementation supports JDBC, HTTP, and Internet Inter-ORB Protocol (IIOP)-based clients.The CMT model allows for implicit or declarative management of transactional behavior through the use of transaction attributes specified in the EJB deployment descriptor. The container begins and ends the transactions as necessary. The CMT transactional behavior of the bean can be changed at application assembly or deployment time, without changing business logic and, thus, it reduces code complexity.



Demarcating Transactions

• Container-managed transactional demarcation:– The <transaction-type> element set to container

in the deployment descriptor– No transactional management code in the bean– Transaction management depends on value of the

<trans-attribute> element – Available to entity, session, and message-driven

beans (MDBs)• Bean-managed transactional demarcation:

– The <transaction-type> element set to bean in the deployment descriptor

– Bean implementation must demarcate the begin, commit, or rollback for the transaction

– Available to session bean and MDBs, but not entity beans

Single Phase Commit: Demarcating Transactions Depending on who demarcates the transaction, the bean or the container creates a new transaction context, starts the transaction, calls the transactional methods on the server objects in the current transaction context, and finally commits or rolls back the transaction. Bean-managed transactional demarcation can also be classified as client-side or server-side, depending on the object that demarcates the transaction. Client-side transaction demarcation is not required by the J2EE specification, and is not recommended for performance and latency reasons. Currently, OC4J does not support remote client-side transaction demarcation. Propagation of the transaction context cannot cross Java virtual machines (JVMs). Thus, neither a remote client nor a remote EJB can initiate or join the transaction.Container-managed demarcations enable you to write EJBs that can be used in different types of applications having different transactional requirements. They also ease the burden on the bean developer by removing the responsibility of keeping track of transactions.Note: The <transaction-type> element appears in only the session bean deployment descriptors. For entity beans, only CMT demarcation is possible, and this tag does not exist.



Container-Managed Transactions

<session><ejb-name>hrApp</ejb-name><home>demos.hrAppHome</home> ...<transaction-type>Container</transaction-type><resource-ref><res-ref-name>jdbc/hrCoreDS</res-ref-name> ...

</session><assembly-descriptor> ...<container-transaction><description>no description</description><method><ejb-name>HrApp</ejb-name><method-name>*</method-name>

</method><trans-attribute>RequiresNew</trans-attribute>

</container-transaction></assembly-descriptor> ...

Container-Managed TransactionsA container-managed transaction is also known as a declarative transaction because you specify the method of transactional management in the J2EE deployment descriptor. Specifying Container for the <transaction-type> in the XML deployment descriptor indicates that the container demarcates the transactions of the bean. That is, the container manages the transactions by providing begin, commit, and rollback statements.Before a bean can be deployed, its transaction attributes must be specified in the deployment descriptor. The transaction attributes can be specified by the bean provider, the application assembler, or the deployer.



CMT: Transaction Attributes

• The following are the EJB-specified values of transaction attributes:– NotSupported– Required– Supports– RequiresNew– Mandatory– Never

• The transactional behavior of a bean can be changed with these attributes during deployment time.

CMT: Transaction AttributesThis slide shows the various values that you can specify for the transaction attributes of EJBs and their methods. These values affect how the container handles the transaction contexts and its propagation to other objects that it calls. The brief explanation of these attribute values and the effect of the attribute values on the invoked bean is as follows:• NotSupported: The existing transaction context is not propagated to the bean. This

attribute applies to stateless session bean (SLSB) and MDB.• Required: The bean always runs in a transaction. This attribute applies to all types

of beans.• Supports: The bean runs in a transaction if the client has one. Otherwise, it runs

without a transaction. This attribute applies to SLSB only.• RequiresNew: The bean always needs a new transaction. This attribute applies to all

types of beans except MDB.• Mandatory: The bean must enter an already-started transaction. This attribute

applies to all types of beans except MDB.• Never: The bean is not allowed in a transaction. This attribute applies to SLSB only.

Generally, you do not need to change the bean code for implementing CMT. However, for some of the transaction attributes above, you need to change the bean class implementation. For example, for using the RequiresNew transaction attribute, you must code the statements to begin and end a new transaction in the bean code.



CMT: Transaction Attributes

You specify the transaction attributes as follows:• Specify for all the methods of a stateful session

bean or an entity bean’s component interface and all direct and indirect superinterfaces of the component interface.

• Do not specify for: – The methods of the javax.ejb.EJBObject

interface and the bean’s home interface in an stateful session bean

– The getEJBHome, getHandle, getPrimaryKey, isIdentical, getEJBMetaData, and getHomeHandle methods in an entity bean

CMT: Transaction Attributes (continued)Transaction attributes should not be specified for the stateful session bean’s home interface.



Transaction Attribute: NotSupported

A client has:• No transaction: The bean does not start one.• A transaction: The bean suspends it. The

transaction resumes when the client gains control.

Client (bean or servlet) Bean

No transactional context

Threads ofexecution



Suspended

Resumed


Transactional context

Transaction Attribute: NotSupportedAn unspecified context means that there is no context associated with the thread.For a bean method whose transaction attribute value is NotSupported, the container invokes the method in an unspecified context. Unspecified transaction context is used in the EJB specification to refer to the cases in which the EJB architecture does not fully define the transaction semantics of an enterprise bean method. This may give unpredictable results. In OC4J, unspecified transaction context is implemented to use no transaction context. It is recommended that the transaction attributes are set at least to Required or RequiresNew.If the client calls the bean with a transaction context, then the container suspends the association of the context from the current thread and resumes the association after the method is complete.If the business method invokes other enterprise beans, then the container passes no transaction context with the invocation.



Threads ofexecution

Transaction Attribute: Required

A client has:• No transaction: The bean starts a new one.• A transaction: The bean uses it.

Client transactional context


Bean

New transactional context

Client (bean or servlet)



Bean

Threads ofexecution

Transaction Attribute: RequiredBean methods with a transaction attribute value of Required must always be invoked in a transaction context. In such cases:

• If a client calls the method with a transaction context, then the container invokes the method in the client’s transaction context.

• If the client call is not associated with a transaction context, then the container starts a new transaction before delegating the method to the bean, and tries to commit the transaction after the method returns and before returning to the client.

• If the bean method invokes other beans, then the container passes the context with the invocation.



Threads ofexecution

Transaction Attribute: Supports

A client has:• No transaction: The bean does not start new one.• A transaction: The bean uses it.

No transactional contextNo transactional context




Bean

Client transactional context

Bean

Threads ofexecution

Transaction Attribute: SupportsBean methods with a transaction attribute value of Supports are invoked as follows:

• If the client calls with a transaction context, then the method is invoked in the client’s transaction context, and the context is passed to any other bean method that the current method calls.

• If the client calls the method without a transaction context, then the method is called with an unspecified transaction context.



Transaction Attribute: RequiresNew

A client has:• No transaction: The bean starts a new one.• A transaction: It is suspended, the bean starts a

new one and commits it, and then the old one resumes.

Bean transactional contextNo transactional context



Client Transactional context

Bean

Bean transactional context

Suspended

Resumed

Threads ofexecution

Transaction Attribute: RequiresNewMethods with the RequiresNew transaction context are always invoked with a new transaction context.If the client invokes the method without any transaction context, then the container starts a new transaction before delegating the call to the client, and tries to commit the transaction after the method is completed and before returning the call to the client.If the client calls with a transaction context, then the container suspends the client’s transaction context and starts a new transaction. The suspended transaction is resumed after the business method and the new transaction are completed.



Threads ofexecution

Transaction Attribute: Mandatory

A client has:• No transaction: The bean requires one. It throws the

javax.transaction.TransactionRequiredException exception.

• A transaction: The bean uses it.




Transactional context Client transactional context

Bean

Bean

EXCEPTION THROWN

Threads ofexecution

Transaction Attribute: MandatoryMethods with a transaction attribute of Mandatory should always be called with a transaction context.If the client calls the method without a transaction context, then the container throws a javax.transaction.TransactionRequiredException exception.If a client calls the method with a transaction context, then the container invokes the method in the client’s transaction context.



Transaction Attribute: Never

A client has:• No transaction: The container calls the method in

an unspecified transaction context.• A transaction: The container throws the

java.rmi.RemoteException exception.

java.rmi.RemoteExceptionTransactional context


Threads ofexecution

Bean

Transaction Attribute: NeverMethods with a transaction attribute of Never should never be called with a transaction context. If the client calls the method with a transaction context, then the container throws a java.rmi.RemoteException exception. If the client calls the method without any transaction context, then the container calls the method in an unspecified transaction context.



CMT: The setRollbackOnly() Method

• The setRollbackOnly() method can control the transaction state in the bean for a CMT.

• The setRollbackOnly() method marks the current transaction for rollback.

• If a transaction is marked for rollback, then the container rolls back the transaction before returning to the caller.

Container-Managed TransactionsIn a CMT bean, the bean cannot, and must not, directly invoke the commit() or rollback() methods to end the transactions.Typically, an enterprise bean marks a transaction for rollback to protect data integrity before throwing an application exception, because an application exception does not automatically cause the container to roll back the transaction. A CMT bean can invoke the javax.ejb.EJBContext.setRollbackOnly() method to set the current transaction to rollback. The bean can use the javax.ejb.EJBContext.getRollbackOnly() method to detect if it has been marked for rollback.



JDeveloper: Setting Transaction Attributes

1. Open the EJB Module Editor for a selected EJB.2. Select the Container Transactions section.3. Use the buttons on the top-right corner to add,

edit, or remove transaction attributes.

Setting Transaction Attributes Using JDeveloperOpen the EJB Module Editor of the CMT EJB to set the transaction attributes.In the Container Transactions section, you can view the existing transaction attributes. Click the Add button to create a new container transaction attribute, the Remove button to delete the selected container transactions attribute, or the Edit button to modify the selected container transaction attribute.By default, the transaction attribute is set to Required for all the methods of the bean.



JDeveloper: Setting Transaction Attributes

1. Select the Transaction Attribute type from the list.2. Select methods from the list and associate them

with the necessary transaction attributes.

Setting Transaction Attributes Using JDeveloper (continued)You can set different transaction attributes for different methods:

1. Select the attribute from the list of attributes available.2. Select methods from the list and associate them with the necessary transaction

attributes.The information selected in this step is included in the EJB’s deployment descriptor. The example in the slide sets the transaction attribute to NotSupported for all the methods of the Departments bean (indicated by *).



Java Transaction API (JTA)

• JTA is used for managing transactions in J2EE.• JTA transactions involve:

– Enlisting resources: Single-phase commit or two-phase commit

– Demarcating transactions: BMT or CMT• The JTA package provides an application interface

(UserTransaction).

Java Transaction API (JTA)JTA is used to explicitly demarcate transactions. A JTA transaction involves enlisting resources (databases). The complexity of your transaction is determined by how many resources your application enlists. Enlisting can be of two types:

• Single-phase commit (1pc), if only a single resource is enlisted in the transaction• Two-phase commit (2pc), if more than one resource is enlisted. The two-phase commit

is more difficult to configure. The two-phase commit mechanism allows transactions to be managed across different servers and databases.

A JTA transaction also involves demarcating the transaction to be a BMT or a CMT.A transaction manager coordinates transactions by propagating the transaction context from one bean to another when invoked by a client, thus ensuring that all the beans invoked during the process are involved in a global transaction. The transaction manager can decide whether changes made by beans can be committed or rolled back, depending on the success or failure of the beans.JTA consists of a high-level transactional client interface and a low-level X/Open XA interface. Only the high-level application interface is discussed in this lesson. This interface is accessible to the beans and is the recommended transactional interface for client applications. The low-level XA interface is used by the EJB server and container to automatically coordinate transactions with resources (such as databases).



JTA: The UserTransaction Interface

• Allows applications to explicitly manage transaction boundaries

• Encapsulates most of the functionality of a transaction manager

public interface javax.transaction.UserTransaction{

public abstract void begin ();

public abstract void commit ();

public abstract int getStatus ();

public abstract void rollback ();

public abstract void setRollbackOnly ();

public abstract void setTransactionTimeout(

int secs); }

JTA: The UserTransaction InterfaceThe UserTransaction interface in the javax.transaction package is the key interface that enables the bean developer to manage the scope of transactions explicitly. begin(): Starts a global transaction and associates it with the current thread. The transaction-to-thread association is done by the transaction manager. commit(): Completes the transaction that is associated with the current thread. When this method completes, the thread is no longer associated with a transaction. getStatus(): Determines the transaction status. The return value can indicate a status of active, no transaction, marked rollback, committed, committing, rolledback, and unknown.rollback(): Rolls back the transaction associated with the current thread and reverts the updates. The thread is no longer associated with a transaction.setRollbackOnly(): Modifies the transaction such that the only outcome of the transaction is to roll back the transaction whether the updates succeeded or failed. Any BMT bean participating in the transaction can invoke this method.setTransactionTimeout(int seconds): Sets the timeout value, which indicates the time before which the transaction should complete. If not called, the transaction manager automatically sets a timeout value. This method must be invoked after the begin()method.



Bean-Managed Transactions Demarcation

• Is indicated by the value Bean for the <transaction-type> element in the deployment descriptor

• Uses the UserTransaction interface of JTA to demarcate and manage the transactions programmatically

By using a UserTransaction object, the bean:• Initializes a transaction context on the client • Invokes the begin(), commit(), or rollback()

methods on the current transaction context to manage the transactions

Bean-Managed Transactions (BMT) DemarcationAn entry <transaction-type>Bean</transaction-type> in the deployment descriptor indicates that a session bean demarcates a transaction programmatically. That is, the bean manages the transactions in its code by providing begin, commit, and rollback statements.Then the begin(), commit(), and rollback() methods of the UserTransactionobject are implemented in the bean. A reference to a javax.transaction.UserTransaction object can be obtained by using the lookup() method on the Java Naming and Directory Interface (JNDI) namespace usingjava:comp/UserTransaction.

For more details about this namespace, refer to Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer’s Guide.



BMT Demarcation: Process

1. Retrieve the UserTransaction object from the bean code by using a JNDI name.

2. Start a transaction by invoking the begin()method on the UserTransaction object.

3. Execute the business logic to be included in the transaction.

4. End the transaction by invoking the commit() or rollback() methods of the UserTransactionobject.

BMT Demarcation: ProcessThe steps in the slide indicate the process of creating BMT demarcation for global transactions. For examples, refer to Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer’s Guide.



Using UserTransaction Support in EJBs

Code example using BMT:

SessionContext ctx;

public void setSessionContext(SessionContext ctx) {

this.ctx = ctx;

}

public beanMethodA() {

UserTransaction utx = ctx.getUserTransaction();

utx.begin();

do work ……

utx.commit();

}

UserTransaction Support in EJB ServerThe sample code shown in the slide is for a BMT bean. In the code sample, you see how the bean saves the reference to the context object in the setContext method and later uses it to get a reference to the userTransaction object.



Client-Demarcated Transactions Using UserTransaction

For Web applications (or EJB client) demarcation:• Get an InitialContext object• Look up java:comp/UserTransaction, and cast

to javax.transaction.UserTransactionContext ctx = new InitialContext (); // Retrieve the UserTransaction object.// Use its methods for transaction demarcationUserTransaction ut = (UserTransaction)

ictx.lookup("java:comp/UserTransaction");ut.begin(); //Start the transaction//Look up bean & access logic to perform sql // If everything went well, commit the transactionut.commit();

Web Application Client Transaction DemarcationAn EJB client, such as a Web application, can initiate a transaction by looking up a javax.transaction.UserTransaction object from the container, as shown in the slide.Note: There is no env pathname in the lookup for java:comp/UserTransaction. The env namespace is generally used for references defined for the component’s enterprise naming context (ENC), which is usually defined in the deployment descriptors of the component.



BMT Demarcation: Restrictions

• Session and message-driven EJBs can have bean-managed transactions if their <transaction-type> element is set to Bean.

• An instance that starts a transaction must complete the transaction before it starts a new transaction.

• A stateful session bean can commit a transaction before a business method ends.

• A stateless session bean must commit the transaction before the business method returns.

BMT Demarcation: RestrictionsWhile an instance is in a transaction, it must not attempt to use the resource manager–specific transaction demarcation.In EJB 1.1, the session beans with the <transaction-type> value of Bean can be BMT beans. MDBs can also have bean-managed transactions. Entity beans can never be BMT beans. Entity beans manage their own transaction attributes for their methods.A stateful session bean can commit a transaction before a business method ends. If a transaction has not been completed by the end of a business method, then the container retains the association between the transaction and instance across multiple client calls until the instance eventually completes the transaction. For sample code, see the previous slides.



Local and Global Transactions

• A local transaction:– Is started and coordinated internally by the

resource manager– Has a single-phase commit

• A global transaction:– Is controlled by a transaction manager external to

the resources involved– Has a two-phase commit

Local and Global TransactionsLocal transactions are started and coordinated internally by the resource manager. Single-phase commit transactions are local transactions.Global transactions are controlled by a transaction manager that is external to the resources involved in the transaction. Two-phase commit transactions that involve more than one resource are global transactions.



Single-Phase Commit

• Configure a data source:– Use the default emulated data source configuration.– Modify the url attribute with the URL of your

database.• Enlist a resource (database): Retrieve a

connection to the data source in the bean after the transaction has begun.– Look up the data source in the JNDI namespace.– Retrieve the connection by using the JTA/JDBC

interface.

Single-Phase CommitConfigure the DataSource in data-sources.xml. For a single-phase commit JTA transaction, use the emulated default data source. Modify this data source url attribute with your database URL information. You retrieve the data source in your code by using a JNDI lookup with the JNDI name configured in the ejb-location attribute. Configure a DataSource for each database that is involved in the transaction. To enlist a single resource in single-phase commit, you must retrieve a connection to that database (the configured data source) before you execute any SQL statements against tables in the database. For these updates to be included in the JTA transaction, you must perform one of the following tasks in your bean implementation after the transaction has begun.

• After the transaction has begun (demarcated), look up the DataSource from the JNDI namespace. You can perform a JNDI lookup on a DataSource definition (as defined in data-sources.xml and ejb-jar.xml) or by using the environment (mapped in orion-ejb-jar.xml). These are discussed later in this lesson.

• Retrieve a connection from this DataSource object by using the getConnection() method.



Data Source Revisited

• A data source is an instantiation of an object that implements the javax.sql.DataSourceinterface.

• You can use a data source to retrieve a connection to a database server.

• A data source offers a portable, vendor-independent method for creating JDBC connections.

• J2EE applications use JNDI to look up DataSource objects.

• Data sources are defined in data-sources.xml.• Data sources can be emulated or nonemulated.

What Is a Data Source?A data source is a Java object that has the properties and methods specified by the javax.sql.DataSource interface. Data sources offer a portable, vendor-independent method for creating JDBC connections. That is, a data source is a JDBC connection factory. J2EE applications use JNDI to look up DataSource objects. Each JDBC 2.0 driver provides its own implementation of a DataSource object, which can be bound into the JNDI namespace, and can be retrieved by using a JNDI look up request. Data sources are the recommended way for J2EE applications to retrieve connections to data servers. In the OC4J environment, data sources are defined in an XML file called data-sources.xml. This configuration file comes with a default definition of a data source, which is sufficient for most of the transactions. Data sources can be emulated or nonemulated. The default data source is an emulated data source. That is, it is a wrapper around Oracle data source objects. You can use this data source for applications that access and update only a single data server. If you need to update more than one database, then you must use a nonemulated data source. This course discusses only single-phase commits. For information about coordinating two-phase commits, refer to Oracle Application Server Containers for J2EE Services Guide.



Default data-sources.xml

<data-sourceclass="com.evermind.sql.DriverManagerDataSource"name="OracleDS"location="jdbc/OracleCoreDS"xa-location="jdbc/xa/OracleXADS"ejb-location="jdbc/OracleDS"connection-driver="oracle.jdbc.driver.OracleDriver"username="scott"password="tiger"url="jdbc:oracle:thin:@localhost:5521:oracle"inactivity-timeout="30"

/>

Default data-sources.xmlThe code in the slide shows the default data source configuration.

• The class attribute defines the type of data source that you want to use.• The location, xa-location, and ejb-location attributes are JNDI names

that the data source is bound to in the JNDI namespace, where:- location identifies a basic data source with no added services. - xa-location identifies a data source with additional support for pooling and

distributed transactions (XA). - ejb-location, used by EJBs, adds support for container-managed

transactions in addition to services provided by the xa-location data source.Note: Always use ejb-location in JNDI lookup requests for a data source for access to all services. In addition, location and xa-location are now obsolete.

• The connection-driver attribute defines the type of connection you expect to be returned to you from the data source.

• The url, username, and password identify the database, its default username, and password.

The data source in the slide example is extremely fast and efficient, because it does not require any JTA or XA operations. To use the OC4J default data source file, modify the data source name, username, password, and connection details with your database information.



Emulated Versus Nonemulated Data Sources

• An emulated data source:– Is valid for a single database and local transactions– Is a wrapper around the Oracle data source– Is useful for Oracle and other databases– Has the

com.evermind.sql.DriverManagerDataSourceclass

• A nonemulated data source:– Is pure Oracle data source implementation– Is needed for two-phase commit and global

transactions– Provides XA and JTA global transaction support– Has the com.evermind.sql.OrionCMTDataSource

class

Emulated Versus Nonemulated Data SourcesEmulated data sources are wrappers around Oracle data sources. If you use these data sources, your connections become extremely fast, because they do not provide full XA or JTA global transactional support. It is recommended that you use emulated data sources for local transactions or when your application operates on a single database. Emulated data sources can be used for Oracle or non-Oracle databases. You can use the emulated data source to obtain connections to different databases by programmatically changing the values of url and connection-driver. To improve efficiency, the connections that are retrieved in a single transaction from the same JNDI-named data source using the same username and password cause the logical connections to share a single physical connection.Local transactions can be used only with a connection retrieved from an emulated data source. If you want to use global transactions, then you must use a nonemulated data source. Nonemulated data sources are pure Oracle data sources. Nonemulated data sources provide XA and JTA global transactional support. Thus, if you want to coordinate modifications in a global transaction, you should use this data source. You can use only these data sources for global two-phase commit transactions. Nonemulated data sources share physical connections for several logical connections to the same database for the same user.



Retrieve Connection to Data Source

<data-sourceclass="com.evermind.sql.DriverManagerDataSource"name="hrCourseDS"location="jdbc/CoreDS"xa-location="jdbc/xa/hrCoreXADS"ejb-location="jdbc/hrCoreDS" ...

/><resource-ref><res-ref-name>jdbc/hrCoreDS</res-ref-name><res-type>javax.sql.DataSource</res-type><res-auth>Container</res-auth>

</resource-ref>

Context ctx = new InitialContext();DataSource ds = (DataSource)

ctx.lookup("jdbc/hrCoreDS");Connection conn = ds.getConnection();

ejb-jar.xml

data-sources.xml

Bean Code

Retrieve Connection to Data SourceAfter the data source is configured, you can retrieve the DataSource object through a JNDI lookup on the data source definition in the data-sources.xml file. The lookup is performed on the logical name of the default data source, which is an emulated data source defined in the ejb-location tag in the data-sources.xmlfile. You must always cast or narrow the object that JNDI returns to the DataSource, because the JNDI lookup() method returns a Java Object. Create a connection to the database represented by the DataSource object by using the getConnection() method of the DataSource object . The getConnection()method takes the schema username and password as defined in the data-sources.xmlfile. Alternatively, you can pass these values as parameters to an overloaded form of this method. After you have the connection, you can construct and execute JDBC statements against this database specified by the data source. In the slide, the J2EE deployment descriptor ejb-jar.xml contains the same logical name in the <res-ref-name> tag as defined in the <ejb-location> tag of the data-sources.xml file. If the two do not match, you must map the data source by using the Oracle-specific deployment descriptor orion-ejb-jar.xml. This process is explained in the next slide.



Retrieve Connection to Data Source

<data-source ...ejb-location="jdbc/hrCoreDS"...

/>

<resource-ref-mapping name="jdbc/HumanResourcesDS" location="jdbc/hrCoreDS"/>

<resource-ref><res-ref-name>jdbc/HumanResourceDS </res-ref-name><res-type>javax.sql.DataSource</res-type><res-auth>Container</res-auth>

</resource-ref>

Context ctx = new InitialContext();DataSource ds = (DataSource)

ctx.lookup("jdbc/HumanResourceDS");

data-sources.xml

orion-ejb-jar.xml

ejb-jar.xml

Bean Code

Retrieve Connection to Data Source (continued)In the slide, the logical name for the data source defined in ejb-jar.xml is different from the ejb-location defined in the data-sources.xml file. In this case, you need to map the JNDI name bound in the data-sources.xml file by using the <res-ref-mapping> element in orion-ejb-jar.xml. Then, retrieve the data source by using the environment JNDI lookup request.The format of the parameter for the JNDI lookup in this case is java:comp/env/jdbc/HumanResourceDS.



Global Transaction Resource Request Flow

• When an EJB requests a JDBC connection or some other transactional resource, it gets associated with the global transaction.

• Consider an EJB with a container-managed transactions (CMT). Assume that:– The client invokes a bean with the transaction

attribute Required– The client is not associated with a global

transaction

Global Transaction Resource Request Flow This section provides a brief description of how an application server can handle a connection request from the application. The diagram in the next slide illustrates the use of JTA. The steps shown are for illustrative purposes and are not prescriptive.Note: The resource request flow is described in the JTA specifications.



Resource Request Flow

Transaction manager

(Oracle10g DB)

Resource adapter

OC4J

Application (Bean)

Client1

2

34

5

6

7

8 9

Resource Request Flow Assuming that a client invokes an EJB with a Required transaction attribute and that the client is not associated with a global transaction, the EJB container starts a global transaction by invoking the TransactionManager.begin() method. The diagram in the slide shows the process of resource request flow, according to the JTA specifications.

1. The client invokes a method on the EJB, and the EJB container starts a global transaction.

2. The OC4J server begins the transaction with the transaction manager on an Oracle database. The command used is TransactionManager.begin().

3. After the transaction starts, the container invokes the bean method. 4. The business logic of the bean makes a request for a connection-based resource by

using the API provided by the resource adapter. The bean invokes JNDI to get the resource (for example, a JDBC data source) using the statement:myDS = ic.lookup("jdbc/hrCoreDS");


Resource Request Flow (continued)5. The container obtains a resource from the resource adapter via the method

ResourceFactory.getTransactionalResource(). The resource adapter creates the TransactionalResource object and the associated XAResourceand Connection objects. The container then invokes the getXAResource()method and obtains the connection as follows:

OracleXADataSource xaDs =new OracleXADataSource();XAConnection axConn = xaDs.getXAConnection();XAResource xaResource = xaconn.getXAResource();

6. The container enlists the resource to the transaction manager by using the statement Transaction.enlistResource(xaRes);

7. The transaction manager invokes the XAResource.start()method to associate the current transaction to the resource.

8. The container invokes the getConnection() method and returns the Connection object reference to the bean.

9. The bean performs operations on the connection by using the JDBC statements such as conn.createStatement();. After the operations are performed, the bean closes the connection by using the statement conn.close();.

The resource adapter notifies the container that the connection is closed, and then the container enlists the resource. The transaction manager then invokes XAResource.end() to dissociate the transaction from the XAResource. The container asks the transaction manager to commit the transaction by using the statement TransactionManager.commit(). The transaction manager invokes XAResource.prepare() to inform the resource manager to prepare the transaction work for commit. The transaction manager then invokes the statement XAResource.commit() to commit the transaction.The transaction is now complete and the client has the control.



Enlisting Database Resources

• The process of including SQL updates in a transaction is called “enlisting.”

• JTA automatically enlists databases opened with a DataSource object in a global UserTransactionobject.

• Since JDK 1.2, a DataSource published into a JNDI namespace is the recommended way to make connections.

• If your global transaction involves more than one database, then you must configure a two-phase commit engine.

Enlisting Database ResourcesEach resource (including databases) that you want managed in the global transaction must be enlisted: JDBC is used to connect to database resources. However, to include all the changes made to multiple databases in a transaction, you must use the JDBC connections in a JTA global transaction. The process of including database SQL updates in a transaction is referred to as enlisting a database resource.The Oracle10g JTA implementation enlists all the databases in which the JDBC connection is opened through the getConnection() method of a JTA DataSource published in the JNDI namespace. For this to happen, you must bind any DataSource object to be used in a JTA transaction with the –dstype jta option of the bindds command. This binds an Oracle-specific JTA DataSource in the namespace. You cannot use any other type of DataSource for global transactions. You see an example of how to do that later in this lesson.You must retrieve the connection in the context of a global transaction; that is, retrieve the connection after the begin() method of the UserTransaction object. The JTA automatically enlists a database resource through a DataSource object. A client or server object opens a JDBC connection to a remote database through the DataSource object in the context of a global transaction. A client can open connections to remote databases through any client JDBC driver.


Enlisting Database Resources (continued)The enlistment of both the default and remote databases depends on an open global transaction context when the database connection is opened. That is, you must retrieve the database connection through the DataSource.getConnection() method after the UserTransaction.begin() method has been invoked.If your transaction involves more than one database, then you must specify an Oracledatabase as the two-phase commit engine. Two-phase commits are not discussed in this course.



Summary

In this lesson, you should have learned how to:• Describe bean-managed and container-managed

transactions• Explain how OC4J supports one-phase and two-

phase transaction protocol logic




This practice covers the following topics:• Deploying a Web application and entity bean with

CMT• Altering the transaction attributes of the methods

in the entity bean, and testing behavior• Optionally, creating a session bean to mediate a

transaction between the Web application and the entity bean methods

Practice 21-1: OverviewThis practice covers the deployment of a Web application and a transaction-enabled entity bean. You then modify the settings of the transactional attributes of the entity bean methods and redeploy the application to test its behavior. Optionally, you create a stateless session bean with a single method to mediate the updating of an employee record between the Web application and the entity bean.


Practice 21-1The goal of this practice is to get some experience working with container-managed transactional attributes. The application you are using here is identical to the one that you used in the previous lesson, without all the security constraints. You still require a valid login, but all users have access to all functions, because security is not the objective of this lab.

1. Open practice21.jws in the practice21 directory, and test the application with default transaction attributes:

a. Deploy the application by using ManageTxApp.deploy fileb. Start your browser and enter the URL http://localhost/managetx to

run the application. Log in as any user, for example jchen, ngreenbe, or ldehaan, with the password oracle.

c. Create a new employee in department 10. Use an employee ID of 900, enter your first name and last name in the first and last name fields, respectively, and enter a job type of IT_PROG. Enter values for all fields.

d. Return to the Welcome employee page, and find all employees in department 10.e. Click the Update link and make a change to the first name and last name, and

delete the last letter from the job type. This job type is invalid and generates an exception for the operation of changing the job type. But what happens to the changes to the first name and last name?

2. Edit the EJB and mark all methods with a transaction attribute of Required. a. Right-click ejb-jar.xml and select Properties. Click Container Transactions

and click the Add button to add a transaction entry. In the Create Container Transaction Entry window select the Required transaction attribute. Click Add Method, select Employees in EJB Name and click * in the methods area. Click OK. Click OK again to close the window.

b. Select Preview XML to observe the <assembly-descriptor> element inside <container-transaction>. Click OK to close the window.

c. Redeploy the application.d. Run the application, search for employees in department 10. Attempt to update

your record again. What happens this time?3. Edit the EJB and mark all methods with a transaction attribute of NotSupported.

a. Right-click ejb-jar.xml and select Properties. Select Container Transactions and click the Transaction Attribute field value in the existing entry. Pick the NotSupported entry from the drop-down list.

b. Select Preview XML to observe the <assembly-descriptor> element inside <container-transaction>. Click OK to close the window.

c. Redeploy the application.d. Run the application, search for employees in department 10. Attempt to update

your record again. What happens this time?4. Edit the EJB module and change the existing transaction attribute entry to mark only

the setXXX() methods with an attribute value of Mandatory. Select Preview XML and note the changes. Click OK to close the window. Hint: Select all the setXXX()methods.

a. Redeploy the application.


Practice 21-1 (continued)b. Run the application and search for employees in department 10. Attempt to

update your record again. What is the result?Hint: Using Notepad look for an exception at the end of the file called E:\ora10gas\opmn\logs\OC4J~home~default_island~1.

5. Modify UpdateEmployee.jsp to use client-demarcated transactions by starting a UserTransaction before calling the entity bean methods to update the employee fields.Hint: Import javax.naming.* and javax.transaction.* to look up a UserTransaction.

a. Redeploy the applicationb. Run the application, search for employees in department 10. Attempt to update

your record again. What happens this time?Optionally, if you have time, then you can perform the following:

6. Create a new stateful session EJB called MaintainEmployee, and set the transactions to be bean managed so that you can create a user transaction to demarcate the transaction boundaries. Make sure that you only use the local interfaces.

a. Add a component method called updateEmployee() that receives the following arguments: java.lang.Long employee_id, java.lang.String first_name, java.lang.String last_name, java.lang.String email, java.lang.String job_id, java.lang.Long salary, java.lang.Long department_id, and returns a java.lang.String.

b. In the MaintainEmployee bean, create a local EJB reference to the entity bean called Employees.

c. Implement the updateEmployee() method to look up the UserTransaction interface, using java:comp/UserTransaction, and start the transaction.Note: Import javax.transaction.UserTransaction.

d. Modify the updateEmployee() method to look up the entity bean by using the getEmployeesLocalHome() method that was added when you created the local EJB reference.Note: import managetx.EmployeesLocal.

e. Add code to updateEmployee(). Change the columns corresponding to the arguments by calling the appropriate set methods of the entity bean instance that you found. Enclose this code in a try/catch block and return the string “Employee Updated” if successful. Otherwise, return the exception message text. Hints: Copy or look at the code in the UpdateEmployee.jsp file. Make sure you use the user transaction object to commit the transaction on success or roll back when there is a failure.

7. Modify the web.xml file to add a local EJB reference with a JNDI name of ejb/local/MaintainEmployee for the MaintainEmployee session bean.Note: Do not overwrite the EJB local reference for Employees entity bean.


Practice 21-1 (continued)

8. Modify UpdateEmployee.jsp to create a MaintainEmployee EJB instance using the JNDI name created in the previous step.

a. Replace the code that uses the entity bean to update the employee by calling the session bean’s updateEmployee() method.

b. Redeploy the applicationc. Run the application, search for employees in department 10. Attempt to update

your record again. What is the result?


Appendix B

Schema Descriptions

Oracle10g: Build J2EE Applications B-2

Order Entry Schema

CUSTOMERS

CUSTOMER_IDCUST_FIRST_NAME CUST_LAST_NAME CUST_ADDRESS PHONE_NUMBERS NLS_LANGUAGE NLS_TERRITORY CREDIT_LIMIT CUST_EMAIL ACCOUNT_MGR_ID CUST_GEO_LOCATIONSTATUS

NUMBER(6)VARCHAR2(20)VARCHAR2(20)CUST_ADDRESS_TYPPHONE_LIST_TYPVARCHAR2(3)VARCHAR2(30)NUMBER(9,2)VARCHAR2(30)NUMBER(6)MDSYS.SDO_GEOMETRYVARCHAR2(10)

ORDER_ITEMS

ORDER_ID LINE_ITEM_ID PRODUCT_ID UNIT_PRICE QUANTITY DISCOUNT_UNIT_PRICE

NUMBER(12)NUMBER(3)NUMBER(6)NUMBER(8,2)NUMBER(8)NUMBER(8,2)

ORDERS

ORDER_ID ORDER_DATE ORDER_MODE CUSTOMER_ID ORDER_STATUSORDER_TOTAL SALES_REP_IDPROMOTION_ID

NUMBER(12)TIMESTAMP(6)VARCHAR2(8)NUMBER(6)NUMBER(2)NUMBER(8,2)NUMBER(6)NUMBER(6)

NUMBER(6)VARCHAR2(50)VARCHAR2(2000)NUMBER(2)NUMBER(1)INTERVAL NUMBER(6)VARCHAR2(20)NUMBER(8,2)NUMBER(8,2)VARCHAR2(50)

PRODUCT_INFORMATION

PRODUCT_ID PRODUCT_NAME PRODUCT_DESCRIPTIONCATEGORY_ID WEIGHT_CLASS WARRANTY_PERIOD SUPPLIER_ID PRODUCT_STATUS LIST_PRICE MIN_PRICE CATALOG_URL

To Product Media

Schema

Oracle10g: Build J2EE Applications B-3

Human Resources Schema

JOB_HISTORY

EMPLOYEE_IDSTART_DATE END_DATE JOB_ID DEPARTMENT_ID

NUMBER(6)DATEDATEVARCHAR2(10)NUMBER(4)

DEPARTMENTS

DEPARTMENT_ID DEPARTMENT_NAME MANAGER_ID LOCATION_ID

NUMBER(4)VARCHAR2(30)NUMBER(6)NUMBER(4)

EMPLOYEES

EMPLOYEE_ID FIRST_NAME LAST_NAME EMAIL PHONE_NUMBERHIRE_DATE JOB_IDSALARYCOMMISSION_PCTMANAGER_IDDEPARTMENT_ID

NUMBER(6)VARCHAR2(20)VARCHAR2(25)VARCHAR2(25)VARCHAR2(20)DATEVARCHAR2(10)NUMBER(8,2)NUMBER(2,2)NUMBER(6)NUMBER(4)

NUMBER(4)VARCHAR2(40)VARCHAR2(12)VARCHAR2(30)VARCHAR2(25)CHAR(2)

LOCATIONS

LOCATION_ID STREET_ADDRESS POSTAL_CODECITY STATE_PROVINCECOUNTRY_ID

JOBS

JOB_IDJOB_TITLE MIN_SALARYMAX_SALARY

VARCHAR2(10)VARCHAR2(35)NUMBER(6)NUMBER(6)

COUNTRIES

COUNTRY_IDCOUNTRY_NAMEREGION_ID

CHAR(2)VARCHAR2(40)NUMBER

REGIONS

REGION_IDREGION_NAME

NUMBERVARCHAR2(25)


BMP Entity EJBsJ2EE Connector Architecture

Oracle10g: Build J2EE Applications D-2

D-2 Copyright © 2004, Oracle. All rights reserved.

BMP Bean: Example

• The example in this lesson creates a BMP entity bean with the following components:– Remote interface: JobsBMP– Home interface: JobsBMPHome– Bean class: JobsBMPBean– Primary key class: JobsBMPPK– Exception class: JobSalException– Deployment descriptor: ejb-jar.xml

• Client for the JobsBMP bean: JobsBMPClient

BMP Bean: ExampleThe entity bean example that is used in this lesson is based on the JOBS table. The JOBStable is a relational table that contains the job_id, job_title, min_salary, and max_salary columns. The description of this table and other tables used in this course are detailed in Appendix B.



Remote Interface: JobsBMP

...public interface JobsBMP extends EJBObject { void incrMinSal(double amt) throws JobSalException, RemoteException;void incrMaxSal(double amt) throwsRemoteException;String getJobTitle()throws RemoteException;void setJobTitle(String title)throwsRemoteException;

double getMinSal()throws RemoteException;void setMinSal(double amt)throws RemoteException;double getMaxSal()throws RemoteException;void setMaxSal(double amt)throws RemoteException;

}

Remote Interface: JobsBMP.javaThe first component that is discussed is the remote interface. The code in the slide shows the remote interface JobsBMP. The container implements this interface, and the implemented object is EJBObject, which is used by the clients to invoke bean methods.The interface should import javax.ejb.EJBObject and java.rmi.RemoteException. The two import statements are necessary because the remote interface extends the EJBObject interface and the methods declared throw RemoteException. All methods that are defined in an interface are public by default.The remote interface declares two business methods (highlighted in blue)—incrMinSal() and incrMaxSal() —to increase the minimum and maximum salaries by the specified amount. The incrMinSal()method throws a user-defined exception JobSalException in addition to the remote exception. The JOBS table contains the following columns: job_id, job_title, min_salary, and max_salary. The remote interface declares the accessor and mutator methods(highlighted in red) for the job_title, min_salary, and max_salary columns.Note: In this lesson, we use remote interfaces. Although an EJB can define both local and remote interfaces, it is not a common practice. If you are in doubt, define remote access to the bean because of scalability and isolation.



Home Interface: JobsBMPHome

...public interface JobsBMPHome extends EJBHome {

JobsBMP create() throws RemoteException,CreateException;

JobsBMP create(String id, String title, doubleminSal, double maxSal) throwsCreateException,RemoteException;

JobsBMP findByPrimaryKey(JobsBMPPK primKey)throws FinderException, RemoteException;

Collection findByMaxSalLimit (double salLimit)throws FinderException, RemoteException;

double getAvgMaxSal() throws JobSalException,RemoteException;

}

Home Interface: JobsBMPHomeThe slide shows the code for the home interface JobsBMPHome. This interface is implemented by the Enterprise JavaBeans (EJB) server and the implemented object is the home object. This object is the factory that is responsible for creating EJB objects.The home interface should import javax.ejb.EJBHome, java.util.Collection, and java.rmi.RemoteException. The home interface extends the EJBHomeinterface. All the methods declared in the home interface must throw the RemoteException exception. java.util.Collection is imported because one of the methods in the home interface (findByMaxSalLimit()) has Collection as its return type. You have already learned that a client uses the home interface reference to create, find, or destroy entity objects. The home interface shown in the slide contains the create() and find() methods. The home interface declares a single create()method that takes the parameters that are necessary for creating a record in the underlying JOBS database table. This method throws the CreateException exception. You should define a corresponding ejbCreate() method in the bean class.


Home Interface: JobsBMPHome (continued)JobsBMPPK is the primary key class that is used in this example. You will see the class definition later in this lesson. An instance of this class is passed as parameter to the findByPrimaryKey()method. The findByPrimaryKey()method finds an entity bean that can be uniquely identified with the given key value, and returns a reference of the bean’s remote interface. The findByMaxSalLimit() method takes a salary limit value as parameter and returns the records that have the maximum salary more than the specified value. Because this may result in more than one row, the return type of this method is Collection. If they cannot find an entity bean instance with the matching value, then the finder methods throw FinderException. getAvgMaxSal()is a home method that is not specific to any particular bean instance. It obtains the average of the max_salary column of the JOBS table. This method throws the user-defined exception JobSalException.



Primary Key Class: JobsBMPPK

import java.io.Serializable;public class JobsBMPPK implements Serializable { public String jobId;

public JobsBMPPK(String id){ this.jobId = id; }

public boolean equals(Object job){...}

public int hashCode(){return super.hashCode();}

public String toString(){ return jobId; }

}

Primary Key Class: JobsBMPPKBecause the JobsBMPPK primary key class implements the java.io.Serializableinterface, the package must be imported. The jobId instance variable is used to locate specific JobsBMP entities or records in the database. This jobId variable maps to the equivalent attribute in the JobsBMPBean bean class that is defined later in this lesson. The EJB specification requires that the fields in the primary key class be declared public.The constructor sets the primary key value to the specified parameter value. The mandatory equals() method compares two cached entity beans by using the primary key to determine whether the two represent the same row in the database.The mandatory hashCode() method stores the primary key internally as a hashtable. The above mandatory methods are invoked only by the container.



User-Defined Exception: JobSalException

public class JobSalException extends Exception{public JobSalException(){ super(); }public JobSalException(Exception e){ super(e.toString()); } public JobSalException(String s) { super(s); }

}

User-Defined Exception: JobSalExceptionThe example in the slide shows the code to create a JobSalException user-defined exception. The incrMinSal(double amt) method throws the JobSalExceptionexception if you try to increase min_salary such that it becomes greater than max_salary. This exception takes a string value as its parameter and passes it to the Exception class. This exception is raised at various locations in the bean class implementation. There are overloaded constructors to throw the exception with a specific string from any method in the bean class.



Bean Class: JobsBMPBean

...

public class JobsBMPBean implements EntityBean {public String id;public String jobTitle;public double maxSal;public double minSal;private Connection conn = null;private EntityContext context;private PreparedStatement ps = null;private ResultSet rset = null;public JobsBMPBean(){

System.out.println("New bean instancecreated");

}...

Bean Class: JobsBMPBeanThe code in the slide is part of the bean class implementation JobsBMPBean. The bean implements the EntityBean interface.You import the following packages that are required for an entity bean to perform Java Database Connectivity (JDBC) operations and to access other classes and interfaces that are used in the bean implementation:

• The javax.ejb package for the interfaces and classes: EntityBean, EntityContext, and ObjectNotFoundException.

• The java.sql package for the Connection, PreparedStatement, and ResultSet classes are required for performing SQL operations for persistence management.

• The javax.sql package for using the data source.• The java.util package for supporting the Collection type, which is the return

type of the home and finder methods in this example.• The javax.naming package for looking up the resources such as DataSource.

Instance variables are declared for holding the context of the entity bean instance, the connection to the database, and the fields of the JOBS table.The no-arg constructor prints a message indicating that a new bean instance is created.




...public JobsBMPPK ejbCreate(String id, String title,double minSal, double maxSal) { try {

this.id = id;this.jobTitle = title;this.minSal = minSal;this.maxSal = maxSal;conn = getConnection();ps = conn.prepareStatement("INSERT INTO jobsVALUES(?,?,?,?)");

ps.setString(1, id);ps.setString(2, jobTitle);ps.setDouble(3, minSal);ps.setDouble(4, maxSal);ps.executeUpdate();

}catch (Exception e) { e.printStackTrace(); }finally { closeConnection(); }return new JobsBMPPK(id);

}...

Bean Class: JobsBMPBean (continued)The code in the slide shows the implementation of the ejbCreate()method. The ejbCreate()method corresponds to the create()method that is declared in the home interface. The ejbCreate() method takes values for the job ID, job title, minimum salary, and maximum salary as parameters. A row is inserted into the table with these details. This method returns the primary key type, JobsBMPPK corresponding to the inserted row.



create() and ejbCreate()

Client

Home object

EJBobject

Entity Beaninstance

Table in database

create()

EJB Object

ejbCreate()

primary key

EJB Container

1 2

345

create() and ejbCreate()The ejbCreate() method in the bean class returns the primary key, whereas the create()method in the home interface returns a reference to the EJB object (JobsBMP).

1. The client requires an EJB object to invoke the methods on the bean. Therefore, the client invokes the create()method.

2. The home object is the factory for creating EJB objects. When a client invokes the create()method, the home object in turn invokes the ejbCreate()method of the bean to create an instance of the bean. The bean instance is created to represent database data.

3. This bean instance should be uniquely identified by the container so that it can be searched or removed from the pool of instances. Therefore, when the ejbCreate()method is invoked by the home object, the bean returns a primary key to the container.

4. After the home object has the primary key, it generates an EJB object.5. The generated EJB object is returned to the client so that the business methods can be

invoked. Therefore, the ejbCreate()method in the bean class returns the primary key, whereas the create()method in the home interface returns a reference to the EJB object.




public void ejbPostCreate(String id, String title, double minSal, double maxSal)

{ } public JobsBMPPK ejbFindByPrimaryKey(JobsBMPPK primKey)

{ try {conn = getConnection();ps = conn.prepareStatement(

"SELECT job_id FROM jobs WHERE job_id = ?");ps.setString(1, primKey.toString());rset = ps.executeQuery();if (!rset.next()) {throw new ObjectNotFoundException("no job with jobID " + primKey); }

ps.close();}

catch (Exception e) { ... }finally { closeConnection(); }return primKey;

}

Bean Class: JobsBMPBeanThe ejbPostCreate()method is called after the ejbCreate()method. Your bean must have one ejbPostCreate()for each ejbCreate()method. You can implement this method to perform any explicit initialization, for setting transaction-related parameters, and so on.The ejbFindByPrimaryKey()method takes the primary key as a parameter. The JOBStable is searched to locate the row with the given job_id as primary key. If the row with the given job_id is not found, then the ObjectNotFoundException exception, which is a subclass of the FinderException exception, is thrown with a message thatthe job with the given job_id is not found. If the row is found, then the primary key isreturned from the method.The method in the example is only testing for a nonexistent row. You can add code to test for more than one matching record found in the table. Finally, the connections are closed.




public void ejbActivate() { }public void ejbPassivate() { }public void setEntityContext(EntityContext ctx){ this.context = ctx; }public void unsetEntityContext(){ this.context = null; }public void ejbRemove(){JobsBMPPK jobId = (JobsBMPPK)context.getPrimaryKey();try {conn = getConnection();ps = conn.prepareStatement("DELETE FROM jobs WHEREjob_id = ?");ps.setString(1, jobId.toString());ps.executeUpdate();

} catch (Exception e1) {...}finally { closeConnection(); } }

Bean Class: JobsBMPBean (continued)The code in the slide shows the callback methods in the bean class.The setEntityContext()method initializes the context of the bean instance. This method associates the bean with context information and is invoked only once by the container when the bean is initialized.The unsetEntityContext() method releases the resources that are not needed by the bean instance when it is destroyed and dissociates the bean from its environment context. The ejbActivate() and ejbPassivate() methods have null implementation, and are invoked by the container before and after an entity bean is swapped out and into the temporary storage.The ejbRemove() method is invoked by the container to remove a bean instance when the client invokes the remove() method on the home object. Because a bean instance can be assigned to a different entity object after it reaches the pool of instances, the method should ensure that it is removing the correct instance. The jobId is obtained from the getPrimaryKey() method of the entity context that is saved with the setEntityContext() method. Then, the JOBS table is searched to find existing records matching with the given primary key, and any such records are deleted. The RemoveException exception is thrown if an attempt is made to remove an EJB object that is not allowed to be removed by the enterprise bean or the container.




public void ejbLoad() {JobsBMPPK key=(JobsBMPPK)context.getPrimaryKey();this.id = key.jobId;try {conn = getConnection();ps = conn.prepareStatement("SELECT job_title,min_salary, max_salary " +"FROM jobs WHERE job_id = ? ");ps.setString(1, id);rset = ps.executeQuery();rset.next();jobTitle = rset.getString("job_title");minSal = rset.getDouble("min_salary");maxSal = rset.getDouble("max_salary");}

...}

Bean Class: JobsBMPBean (continued)The code in the slide shows the ejbLoad() method. This method is developed by the bean developer in a BMP entity bean. This method loads the data that is saved within the persistent storage into the bean. The container invokes this method within a transaction when the data should be reinitialized from the database. This normally occurs after the transaction begins.You obtain jobId from the getPrimaryKey() method of the entity context that is saved with the setEntityContext() method. You then search the JOBS table to find the record that matches the given primary key. Next, you load this record into the instance variables that are declared at the beginning of the bean class implementation definition.




public void ejbStore() {JobsBMPPK key= (JobsBMPPK)context.getPrimaryKey();String id = key.jobId;try {

conn = getConnection();ps = conn.prepareStatement("UPDATE jobs SET job_title=?, min_salary=?,max_salary=? WHERE job_id = ?");

ps.setString(1, jobTitle);ps.setDouble(2, minSal);ps.setDouble(3, maxSal);ps.setString(4, id);ps.executeUpdate();}

...}

Bean Class: JobsBMPBean (continued)The code in the slide shows the ejbStore() method. This method stores the data that is represented by the in-memory entity bean instance into the persistent storage. The container invokes this method immediately before a transaction commits, or when the bean is removed, to save the existing values of the persistent data. The ID is obtained from the getPrimaryKey() method of the entity context that is saved with the setEntityContext() method. Then the JOBS table is searched to find existing records that match the given primary key and any such records are updated. In the above example, all the columns except for one are being modified. If only a few columns are to be modified, then the bean can optimize the update by specifying the column names in the UPDATE statement.




public void incrMinSal(double amt)throws JobSalException {if ((minSal + amt) > maxSal)

{ throw new JobSalException ("You cannotincrease min salary to be more than " +maxSal);}

else { minSal += amt; } } public void incrMaxSal(double amt)

{ maxSal += amt; }public String getJobTitle()

{ return jobTitle; }public void setJobTitle(String title)

{ this.jobTitle = title; }public double getMinSal()

{ return minSal; }

Bean Class: JobsBMPBean (continued)The code in the slide shows the implementation for business methods, accessor methods, and mutator methods of the bean class implementation JobsBMPBean. These methods are declared in the remote interface of the bean.The incrMinSal()method increases the minimum salary by the specified amount. If adding the amount increases the minimum salary beyond the the maximum salary for the job, then the method throws the user-defined JobSalException exception.The incrMaxSal()method increases the maximum salary for the job by the specifiedamount.The getxxx methods return the value of the variable, for which they are defined.The setxxx methods set the value of the variable with the value specified in the parameter.




public void setMinSal(double amt){ this.minSal = minSal; }

public double getMaxSal() { return maxSal; }public void setMaxSal(double amt)

{ this.maxSal = maxSal; }private Connection getConnection() throws SQLException{ DataSource ds=null;

try { Context ctx = new InitialContext();ds=(DataSource)ctx.lookup("java:comp/env/jdbc/hrDS");

} catch (NamingException e){ System.out.println("Could not get connection");

e.printStackTrace();throw new SQLException(e.getMessage());

}return ds.getConnection();

}

Bean Class: JobsBMPBean (continued)The code in the slide shows the accessor methods for the minSal and maxSal variables.The getConnection()method is used to obtain a connection to the data source for manipulating the database. The data source is defined in the data-sources.xml file and the mapping can be specified in the deployment descriptor. The method obtains an initial context and looks up the data source with that context. The data source in the example is called hrDS. The method returns the connection by invoking the getConnection()method on the DataSource object. If there is an error in obtaining the connection, then the method throws an exception.The DataSource object is from the javax.sql package. The name of this object must match the name that is shown in the <ejb-location> element of the data-sources.xml file.




private void closeConnection (){ try { if (rset != null) rset.close();}

catch (Exception e) {...}try { if (ps != null) ps.close();}

catch (Exception e) {...}try { if (conn != null) conn.close(); }

catch (Exception e) {...}}

Bean Class: JobsBMPBean (continued)The closeConnection() method is invoked at the end of each method that uses the SQL connection obtained through getConnection(). It closes the prepared statement and the connection. Therefore, the container is able to reuse the connection.




public double ejbHomeGetAvgMaxSal()throws JobSalException {try {

conn = getConnection();ps = conn.prepareStatement

("SELECT AVG(max_salary) as AvgMax FROM jobs");rset = ps.executeQuery();

if (rset.next()) return rset.getDouble("AvgMax");}

catch (Exception e) {e.printStackTrace();throw new JobSalException(); }

finally { closeConnection(); } throw new JobSalException ("Error in the method");}

Bean Class: JobsBMPBean (continued)The ejbHomeGetAvgMaxSal()method is the implementation of the home method getAvgMaxSal(). The home method in the bean class has a prefix of ejbHome and the method name is capitalized. This method obtains a connection and uses JDBC calls to retrieve the average of the max_salary column of the JOBS table. This method is not specific to any particular bean instance. Finally, the connections are closed by invoking the closeConnection()method.



Bean Class: JobsBMPBeanpublic Collection ejbFindByMaxSalLimit(double salLimit) {Vector v = null;try {v = new Vector();conn = getConnection();ps = conn.prepareStatement ("SELECT job_idFROM jobs WHERE max_salary > ? ");ps.setDouble(1,salLimit);rset = ps.executeQuery();while (rset.next()) {String id = rset.getString("job_id");v.addElement(new JobsBMPPK(id));}

} catch (Exception e) {...}finally { closeConnection(); }return v;}

}

Bean Class: JobsBMPBean (continued)The slide shows the code for the ejbFindByMaxSalLimit() method. It takes a salary limit as parameter. This method corresponds to the findByMaxSalLimit() method that is declared in the home interface of the bean. The JOBS table is searched to locate the rows in which max_salary is greater than the given salary limit. If no rows are found, then FinderException is thrown. Because there can be more than one row satisfying the search condition, the results are collected into a Vector. Each result is converted into a primary key before being added to the Vector, and the Vector is returned from the method.



Deployment Descriptor...<ejb-jar><enterprise-beans><entity><ejb-name>JobsBMP</ejb-name><home> demos.JobsBMPHome</home><remote>demos.JobsBMP</remote><ejb-class>demos.JobsBMPBean</ejb-class><persistence-type>Bean</persistence-type><prim-key-class>demos.JobsBMPPK</prim-key-class><reentrant>False</reentrant>

<resource-ref><res-ref-name>jdbc/hrDS</res-ref-name><res-type>javax.sql.DataSource</res-type><res-auth>Application</res-auth>

</resource-ref> </entity> ...

Deployment Descriptor The slide shows the <entity> tag of the deployment descriptor for the JobsBMPexample. The <entity> tag indicates that the deployment descriptor is for an entity bean.The logical name for the EJB is given as JobsBMP in the <ejb-name> element. The remote home and remote interface names are given along with their packages names. If the bean has local interfaces (can be in addition to the remote interfaces), those references should also be added to the <entity> tag. The value Bean for the <persistence-type> element indicates that the entity bean is a bean-managed persistence bean. The <prim-key-class> element shows that JobsBMPPK is the primary key class. The <reentrant> flag is set to false because the JobsBMP bean does not call itself.The <resource-ref> element indicates that the SQL data source hrDS is authenticated by the container. This data source specified in the <res-ref-name> element is generally the value of an <ejb-location> element in the data-sources.xml file. The value for the <res-auth> element can be either container or Application. This element specifies whether authorization to the resource must be performed by the container or programmatically through the application.



...</enterprise-beans><assembly-descriptor><container-transaction><method><ejb-name>JobsBMP</ejb-name><method-name>*</method-name></method> <trans-attribute>Required</trans-attribute>

</container-transaction></assembly-descriptor>

</ejb-jar>

Deployment Descriptor

Deployment Descriptor (continued)Note that the deployment descriptor contains two main tags. One is the <enterprise-beans> tag (which holds information about the bean, the persistence, and the data source information). The other is the <assembly-descriptor> element that describes the transaction properties of the BMP bean. A transaction is a series of database operations that execute as a single unit. In case of transactions, all the operations must be successfully completed, followed by a commit operation. Otherwise, there is a rollback. Transactions can be bean-managed transactions (BMT) or container-managed transactions (CMT). You learn about these in the next few slides. The <container-transaction> tag of the <assembly-descriptor>element contains all the transaction attributes of the bean. The methods for which the transaction must be managed are specified in the <method>tag. A value * for <method-name> indicates that the container must manage transactionsfor all methods in the bean. The value Required for <trans-attribute> indicates that the bean always runs in a transaction.



<?xml version="1.0" standalone='yes'?>... <data-sources><data-source

class="com.evermind.sql.DriverManagerDataSource"name="OracleDS"location="jdbc/OracleCoreDS"xa-location="jdbc/xa/OracleXADS"ejb-location="jdbc/hrDS"

connection-driver="oracle.jdbc.driver.OracleDriver"url="jdbc:oracle:thin:@localhost:1521:orcl"username="hr"password="hr"inactivity-timeout="30"

/></data-sources>

Creating Data Source data-sources.xml

Creating Data Source data-sources.xmlYou have already learned about data sources. Data sources provide logical definitions of databases. A bean developer uses logical representation of a database in the bean class, which the deployer maps to physical data sources. Data sources are published in the Java Naming and Directory Interface (JNDI) tree and are bound to the java:comp/env JNDI. Java 2, Enterprise Edition (J2EE) applications use published DataSource objects by performing lookup via JNDI using the published name, and use connection methods to connect to the database. Global data sources are defined in $OC4J_HOME/config/data-sources.xml. Each data source is specified with an XML tag. Application-specific data source files are specified by using the <data-sources> tag in the orion-application.xml file.The data source that is specified in the <res-ref-name> element of the ejb-jar.xmldeployment descriptor corresponds to a <ejb-location> element in the data-sources.xml file. The two elements need not have the same name. If the names of these two elements are different, then you need to map the elements through the orion-ejb-jar.xml file.


Creating Data Source data-sources.xml (continued)The jdbc/hrDS data source is configured in the data-sources.xml file, as shown in the slide. The URL for the JDBC connection and the username and password to access the database schema are also specified. The default port number and SID on NT are 1521 and ORCL. Oracle Application Server 10g Containers for J2EE (OC4J) ships with a default JDBC port number 5521. The username and the password are those of the schema being used.The various attributes specified in the data-sources.xml file are as follows:

• The class attribute in the XML file defines the DataSource class to use. • The name attribute is used to identify this data source and defaults to a value of

Location if none is supplied. • The location attribute defines the logical name for the data source and returns a

data source as specified in the class attribute. • The connection-driver attribute defines the JDBC driver for this data source. • The ejb-location attribute specifies the logical name for the EJB CMP data

source and supports pooling and transactional semantics. • The xa-location (mandatory if ejb-location is present) attribute specifies the

logical name for the transaction-enabled data source. Data sources are mapped by using OC4J descriptors <resource-ref-mapping>.



Client Class: JobsBMPClient

import javax.ejb.*;import java.rmi.RemoteException;import java.sql.*;import java.util.*;import javax.naming.*;public class JobsBMPClient {public static void main(String[] args) { JobsBMP jobs = null;try {Context context = getInitialContext();JobsBMPHome jobsBMPHome = (JobsBMPHome)PortableRemoteObject.narrow

(context.lookup("JobsBMP"),JobsBMPHome.class);JobsBMP jobsBMP;

jobsBMP = jobsBMPHome.create("job_dev", "Bean Developer", 3000, 5000);

...

Client Class: JobsBMPClientThe code in the slide is a stand-alone client JobsBMPClient. This client obtains the initial context for the home object. The client invokes the create()method to create a bean with the job ID job_dev.



Client Class: JobsBMPClient... jobsBMP.incrMinSal( 200.0 );System.out.println ("min_salary after incrementing

" + jobsBMP.getMinSal( ));jobsBMP.incrMaxSal( 600.0 );System.out.println ("max_salary after incrementing

" + jobsBMP.getMaxSal( ));System.out.println("printing job_title "+

jobsBMP.getJobTitle( ));Collection

col=jobsBMPHome.findByMaxSalLimit(15000);Iterator it = col.iterator();while (it.hasNext()){JobsBMP jobSals = (JobsBMP)it.next();System.out.println(jobSals.getMaxSal());} }catch(Throwable ex) {...} }

...

Client Class: JobsBMPClient (continued)Various methods are invoked on the bean instance to test the methods.The client increases the minimum salary by 500 and invokes the accessor method to display the minimum salary. The client uses the findByMaxSalLimit() method and searches for rows from the underlying database whose maximum salary is more than 15,000. The rows are stored in an iterator and an exception is thrown if there are no matching rows.



Overview of J2EE Connector Architecture

• The J2EE Connector Architecture (JCA) enables J2EE components to interact with Enterprise Information Systems (EISs) such as:– Enterprise resource planning (ERP)– Mainframe transaction processing– Databases and nonrelational systems, and so on

• JCA simplifies the integration of diverse EISs. Adherence to the JCA specification makes an EIS implementation portable across compliant J2EE servers.

Overview of J2EE Connector ArchitectureThe J2EE Connector Architecture (JCA) is a required J2EE 1.3 API defining a standard architecture for connecting the J2EE platform components (such as Enterprise JavaBeans) to heterogeneous Enterprise Information Systems (EISs). Examples of EISs include ERP, mainframe transaction processing, database systems, and legacy applications that are not written in the Java programming language.Each EIS requires only one JCA implementation that adheres to the J2EE Connector Specification. Adherence to the specification makes the implementation portable across compliant J2EE servers.



OC4J J2EE Connector Architecture

Basic J2EE Connector Architecture:

OC4J

J2EE ApplicationComponent

ResourceAdapter

Enterprise Information

System

ApplicationContract

SystemContracts(Quality ofService)

OC4J J2EE Connector ArchitectureThe slide shows how OC4J implements the standard Java Connector Architecture (JCA).A resource adapter is a J2EE component implementing JCA for a specific EIS. The resource adapter mediates communication between the J2EE component (by using JCA) and the associated Enterprise Information System. The resource adapter implements two kinds of contracts for the JCA application component:

• Application Contract, which defines the interfaces or API through which the J2EE component accesses the EIS. The API, provided by the resource adapter, can either be the standard Common Client Interface (CCI), or an API specific to the type of a resource adapter and its underlying EIS.

• System Contracts, also known as Quality of Service (QoS) contracts that provide access to the following services managed by the J2EE container:

- Connection services for pooling connections to the EIS- Transaction services to enable use of a transaction manager for distributed

transactions- Security services for authentication, authorization, and secure communication

with the EIS



What Is a Resource Adapter?

It is a driver used by a client application to connect to a specific EIS.• OC4J provides support for two J2EE 1.3 types:

– A stand-alone resource adapter, which is found in a Resource Adapter Archive (RAR) file for use by all deployed applications

– An embedded resource adapter, which is bundled in an EAR file for a specific enterprise application

• Examples of resource adapters:– JDBC or SQL for Java (SQLJ) drivers for database

connections– ERP adapter to connector a specific ERP

What Is a Resource Adapter?A resource adapter is a driver used by an application server or an application client to connect to a specific EIS. Examples of resource adapters are JDBC or SQLJ drivers to connect to a relational database, an ERP resource adapter to connect to an ERP system, and a TP resource adapter to connect to a TP monitor. J2EE 1.3 requires application servers to support both stand-alone and embedded resource adapters.Stand-alone resource adapters, manifested in the form of a stand-alone Resource Adapter Archive (RAR) file, is available to all deployed applications. The following is an example of the contents of a RAR file.

/META-INF/ra.xml /META-INF/oc4j-ra.xml /howto.html /images/icon.jpg /ra.jar /win.dll

Note: The list of files in a RAR can vary. Embedded resource adapters are added to enterprise application archive (EAR), and is only available to the J2EE application with which it is packaged.



Resource Adapter Deployment Descriptors

OC4J provides the following deployment descriptors for resource adapters:• ra.xml: A standard J2EE deployment descriptor

for developing an adapter• oc4j-ra.xml: Contains deployment

configurations for deploying an adapter to OC4J• oc4j-connectors.xml• One oc4j-connectors.xml file: Contains a list of

stand-alone resource adapters deployed. It is located in the ORACLEAS_HOME/j2ee/home/config directory.

Resource Adapter Deployment DescriptorsIn the previous pages, you should have noticed an ra.xml and an oc4j-ra.xml file contained in the RAR file.The ra.xml is a standard J2EE deployment descriptor for developing against a resource adapter.The oc4j-ra.xml contains deployment configurations for deploying resource adapters to OC4J. It contains EIS connection information as specified in the deployment descriptor of the resource adapter (ra.xml), the JNDI name to be used, connection pooling parameters, and resource principal mappings (<security-config> elements). In each OC4J instance, there should be one oc4j-connectors.xml file, located in the ORACLEAS_HOME/j2ee/home/config directory, listing all the stand-alone resource adapters that have been deployed in this OC4J instance. For example:

<oc4j-connectors> <connector name="myEIS" path="eis.rar">

<native-library>lib</native-library> </connector>

</oc4j-connectors>



Deploying Stand-Alone Resource Adapters

When deploying stand-alone adapters:• Give the resource adapter a unique name, to

simplify future operations such as removal of a deployed resource adapter

• Deploy in one of the following two ways:– Using the Admin command-line tool (admin.jar)– Manually through directory manipulation, by

expanding the .rar file contents into a user-specified directory name <connector-name> below the ORACLEAS_HOME/j2ee/home/<connector directory> (which defaults to ORACLEAS_HOME/j2ee/home/connectors)

Deploying Stand-Alone Resource AdaptersWhen deploying stand-alone resource adapter archives in OC4J, assign it a unique name for future operations such as removal of a deployed resource adapter. Resource adapters can be deployed in OC4J in one of the following two ways:

• By using the Admin command-line tool (admin.jar)• Manually through manipulation of directories

The Admin tool requires a -deployconnector switch, for example:java -jar admin.jar ormi://host admin password

-deployconnector -name myname -file myconnector.rar

OC4J decompresses the .rar file into a <connector-directory>/<connector-name> directory below the ORACLEAS_HOME/j2ee/home directory for the OC4J instance. If the directory does not exist, it will be created. A new attribute connector-directory should be added to the <application-server> element in the application-server.xml file to specify the path used for the storage of stand-alone resource adapters. The default directory is ../connectors relative to the OC4J configdirectory. In the above example, OC4J decompresses myconnector.rar into a directory called ORACLEAS_HOME/j2ee/home/connectors/myname. The deployment tool must also verify the transaction levels, and whether the authentication specified in the deployment descriptor of the resource adapter (ra.xml) is supported by OC4J.



Deploying Embedded Resource Adapters

• Embedded resource adapters are packaged and deployed inside an Enterprise Application Archive (EAR) file.

• Each application (from an EAR file) has one oc4j-connectors.xml file.

• The application oc4j-connectors.xml file lists all the resource adapters deployed in the EAR file.

• The oc4j-connectors.xml file is automatically generated if not already included in the EAR file.

Deploying Embedded Resource AdaptersEmbedded resource adapters are packaged inside an Enterprise Application Archive (EAR) file. If a resource adapter archive (for example, myconnecter.rar) is packaged in an EAR file (that is, myapp.ear), then the application is deployed in OC4J, in the directory ORACLEAS_HOME/j2ee/home/applications/myapp/myconnecter_rar. Each application deployed in an OC4J instance containing resource adapters, should have one oc4j-connectors.xml file located in the directory ORACLEAS_HOME/j2ee/home/application-deployments/<app-name>/. The oc4j-connectors.xml file contains the list of resource adapters for a Web application packaged in an EAR file (one entry for each resource adapter). The name and path of the oc4j-connectors.xml file is defined in a new element called <connectors> inside the <orion-application> element in orion-application.xml. If no <connectors> element is specified in orion-application.xml, then the default file will be called oc4j-connectors.xml. Assume that an oc4j-connectors.xml file that specifies a deployment name “myRA,”is in the .ear file. The generated oc4j-ra.xml file will be located in the ORACLEAS_HOME/j2ee/home/application-deployment/myapp/myRA/directory. If omitted from the EAR file, an oc4j-connectors.xml file is created in the ORACLEAS_HOME/j2ee/home/application-deployment/myapp/ directory .



Common Client Interface (CCI) API

CCI is defined by the J2EE Connector Architecture specification as:• A set of interfaces and classes to allow a J2EE

component to perform data access operations with an EIS

• Main interfaces and classes are:– ConnectionFactory– Connection– Interaction– RecordFactory– Record

(Use Sun’s Java J2EE Tutorial for more information.)

Common Client Interface (CCI) APIThe J2EE Connector Architecture specification defines the Common Client Interface (CCI) API. CCI defines a set of interfaces and classes with methods that allow a client application to perform data access operations with the EIS. The main interfaces and classes are:• ConnectionFactory: To create Connection instances to an EIS • Connection: Representing a specific connection to the EIS• Interaction: Used to execute the EIS functionality, such as a stored procedure• RecordFactory: Creates Record instances for an application component • Record: A superclass for the following types of instances: MappedRecord,

IndexedRecord, or ResultSet. An IndexedRecord is an ordered collection based on the java.util.List interface.

A client or application component uses the CCI API to establish a connection to the EIS’s resource manager by using the ConnectionFactory interface. The Connectionobject created is used for interactions with the EIS. The component accesses data from an EIS by using an Interaction object through the details specified in an InteractionSpecobject. When data is read from (or written to) the EIS tables (or file structures), it uses one of the Record instance types, either a MappedRecord, IndexedRecord, or ResultSet.