PK
xˆ:Moa«, mimetypeapplication/epub+zipPK xˆ:M META-INF/container.xmlâ ÿ
This chapter describes the contents and organization of this guide—Developing Enterprise JavaBeans for Oracle WebLogic Server 12.1.3.
This chapter includes the following sections:
This document is a resource for software developers who develop applications that include WebLogic Server Enterprise JavaBeans (EJBs).
The document mostly discusses the Java EE 6-based, EJB 3.1 programming model, in particular the use of metadata annotations to simplify development. This document does not address EJB topics that are different between versions 2.x and 3.x, such as design considerations, EJB container architecture, entity beans, deployment descriptor use, and so on. This document also does not address production phase administration, monitoring, or performance tuning. For links to WebLogic Server documentation and resources for these topics, see Related Documentation.
It is assumed that the reader is familiar with Java Platform, Enterprise Edition (Java EE) Version 6 and basic EJB programming concepts.
For information on programming and packaging 2.1 EJBs, see Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.
This chapter, Chapter 1, "Introduction and Roadmap," introduces the organization of this guide.
Chapter 2, "Understanding Enterprise JavaBeans," provides an overview of the new EJB 3.1 features, as well as a brief description of the differences between EJB 3.1 and 3.0.
Chapter 3, "Simple Enterprise JavaBeans Examples," provides examples of programming EJBs using the metadata annotations specified by EJB 3.x.
Chapter 4, "Iterative Development of Enterprise JavaBeans," describes the EJB implementation process, and provides guidance for how to get an EJB up and running in WebLogic Server.
Chapter 5, "Programming the Annotated EJB Class," describes the requirements and typical steps when programming the EJB bean class that contains the metadata annotations.
Chapter 6, "Deployment Guidelines for Enterprise JavaBeans," discusses EJB-specific deployment issues and procedures.
Chapter 7, "Using an Embedded EJB Container in Oracle WebLogic Server," discusses using an embeddable EJB container in Oracle WebLogic Server.
Chapter 8, "Configuring the Persistence Provider in Oracle WebLogic Server," provides an overview of developing an Oracle TopLink application using Oracle WebLogic Server.
Appendix A, "EJB Metadata Annotations Reference," provides reference information for the EJB 3.0 metadata annotations, as well as information about standard metadata annotations that are used by EJB.
Appendix B, "Using Oracle Kodo with Oracle WebLogic Server," describes how to use Oracle Kodo to create entity beans. Oracle Kodo is a product that provides the implementation of the Java Persistence API section of the EJB 3.0 specification, as well as other persistence-related technologies such as Java Data Objects (JDO).
Note: Oracle Kodo JPA/JDO is deprecated in this release. Customers are encouraged to use Oracle TopLink, which supports JPA 2.0. Kodo supports only JPA 1.0. |
Appendix C, "Oracle Kodo Persistence Configuration Schema Reference," provides reference information for the persistence configuration schema.
This document contains EJB 3.1-specific development information. Additionally, it provides information only for session and message-driven beans. For complete information on general EJB design and architecture, the EJB 2.x programming model (which is fully supported in EJB 3.1), see the following documents.
For information about developing and deploying EJBs with WebLogic Server, see:
"Enterprise Java Beans (EJBs)" in Understanding Oracle WebLogic Server.
For instructions on how to organize and build WebLogic Server EJBs in a split directory environment, see Developing Applications for Oracle WebLogic Server.
For information on programming and packaging 2.x EJBs, see Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.
Deploying Applications to Oracle WebLogic Server is the primary source of information about deploying WebLogic Server applications in development and production environments.
It is assumed the reader is familiar with programming in Java EE 6 and EJB 3.1 concepts and features. To learn more about basic EJB concepts, such as the benefits of enterprise beans, the types of enterprise beans, and their life cycles, then visit the following Web sites:
Enterprise JavaBeans 3.1 Specification (JSR-318) at http://jcp.org/en/jsr/summary?id=318
The "Enterprise Beans" chapter of the Java EE 6 Tutorial at http://docs.oracle.com/javaee/6/tutorial/doc/bnblr.html
Introducing the Java EE 6 Platform: Part 3 (EJB Technology, Even Easier to Use) at http://www.oracle.com/technetwork/articles/javaee/javaee6overview-part3-139660.html#ejbeasy
In addition to this document and the basic examples described in Chapter 3, "Simple Enterprise JavaBeans Examples,", Oracle provides comprehensive examples in the WebLogic Server distribution kit.
WebLogic Server optionally installs these in EXAMPLES_HOME/wl_server/examples/src/examples
, where EXAMPLES_HOME
represents the directory in which the WebLogic Server code examples are configured. For more information, see "Sample Applications and Code Examples" in Understanding Oracle WebLogic Server.
Oracle recommends that you run these examples before programming your own application that uses EJBs.
Oracle provides Java EE 6 examples that demonstrate new features in EJB 3.1, such as:
EJB 3.1: Example of Simplified No-interface Programming and Packaging in a WAR File
EJB 3.1: Example of Using a Portable Global JNDI Name in an EJB
For more information, see these examples in the WebLogic Server distribution kit: EXAMPLES_HOME/wl_server/examples/src/examples/javaee6/ejb
where EXAMPLES_HOME
represents the directory in which the WebLogic Server code examples are configured. For more information, see "Sample Applications and Code Examples" in Understanding Oracle WebLogic Server.
There is also an EJB 3.0 persistence service example, EJB 3.1: Example of Using the Embeddable EJB Container in Java SE, that includes actual business code and provides practical instructions on how to perform key EJB 3.0 development tasks. In particular, the example demonstrates usage of EJB 3.x with:
Java Persistence API
Stateless Session Bean
Message Driven Bean
Asynchronous JavaScript based browser application
The example uses a persistent domain model for entity EJBs. For more information, see the example in the WebLogic Server distribution kit: EXAMPLES_HOME/wl_server/examples/src/examples/ejb/ejb30
where EXAMPLES_HOME
represents the directory in which the WebLogic Server code examples are configured. For more information, see "Sample Applications and Code Examples" in Understanding Oracle WebLogic Server.
For a comprehensive listing of the new features in EJB 3.1 features introduced in this release of WebLogic Server, see "Enterprise Java Beans (EJBs)" in What's New in Oracle WebLogic Server.
This preface describes the document accessibility features and conventions used in this guide—Developing Enterprise JavaBeans for Oracle WebLogic Server 12.1.3.
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc
.
Access to Oracle Support
Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info
or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs
if you are hearing impaired.
The following text conventions are used in this document:
Convention | Meaning |
---|---|
boldface | Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary. |
italic | Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values. |
monospace | Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter. |
This chapter describes the new features and programming model of EJB 3.1 and also provides a basic overview of the EJB components, anatomy, and features used in WebLogic Server 12.1.3.
This chapter includes the following sections:
These sections summarize the changes in the EJB programming model and requirements between EJB 3.0 and 3.1, as well between EJB 2.x and 3.0.
The EJB 3.1 specification provides simplified programming and packaging model changes. The mandatory use of Java interfaces from previous versions has been removed, allowing plain old Java objects to be annotated and used as EJB components. The simplification is further enhanced through the ability to place EJB components directly inside of Web applications, removing the need to produce separate archives to store the Web and EJB components and combine them together in an EAR file.
For a comprehensive listing of the new features in EJB 3.1 features introduced in this release of WebLogic Server, see "Enterprise Java Beans (EJBs)" in What's New in Oracle WebLogic Server.
Singleton Session Bean – singleton session beans provide a formal programming construct that guarantees a session bean will be instantiated once per application in a particular Java Virtual Machine (JVM), and that it will exist for the life cycle of the application. With singletons, you can easily share state between multiple instances of an enterprise bean component or between multiple enterprise bean components in the application.
Simplified No Interface Client View – The No-interface local client view type simplifies EJB development by providing local session bean access without requiring a separate local business interface, allowing components to have EJB bean class instances directly injected.
Packaging and Deploying EJBs Directly in a WAR File – EJB 3.1 provides the ability to place EJB components directly inside of Web application archive (WAR) files, removing the need to produce archives to store the Web and EJB components and combine them together in an enterprise application archive (EAR) file.
Portable Global JNDI Names – The Portable Global JNDI naming option in EJB 3.1 provides a number of common, well-known namespaces in which EJB components can be registered and looked up from using the pattern java:global[/<app-name>]/<module-name>/<bean-name>
. This standardizes how and where EJB components are registered in JNDI, and how they can be looked up and used by applications.
Asynchronous Session Bean Invocations – An EJB 3.1 session bean can expose methods with asynchronous client invocation semantics. Using the @Asynchronous
annotation in an EJB class or specific method will direct the EJB container to return control immediately to the client when the method is invoked. The method may return a future object to allow the client to check on the status of the method invocation, and retrieve result values that are asynchronously produced.
EJB Timer Enhancements – The EJB 3.1 Timer Service supports calendar-based EJB Timer expressions. The scheduling functionality takes the form of CRON-styled schedule definitions that can be placed on EJB methods, in order to have the methods be automatically invoked according to the defined schedule. EJB 3.1 also supports the automatic creation of a timer based on metadata in the bean class or deployment descriptor, which allows the bean developer to schedule a timer without relying on a bean invocation to programmatically invoke one of the Timer Service timer creation methods. Automatically created timers are created by the container as a result of application deployment.
Embeddable EJB Container – EJB 3.1 supports an embeddable API for executing EJB components within a Java SE environment. Unlike traditional Java EE server-based execution, embeddable usage allows client code and its corresponding enterprise beans to run within the same virtual machine and class loader. This provides better support for testing, offline processing (e.g., batch jobs), and the use of the EJB programming model in desktop applications.
JPA 2.0 Support – Oracle EclipseLink is the default JPA 2.0 persistence provider that is shipped with Oracle WebLogic Server. Oracle Kodo was deprecated in Oracle Fusion Middleware 11gR1 (11.1.1.1.0) (Oracle WebLogic Server 10.3.1). WebLogic Server runs with the JPA 2.0 JAR in the server classpath
. Although JPA 2.0 is upwardly compatible with JPA 1.0, JPA 2.0 introduced some methods to existing JPA interfaces that conflict with existing signatures in OpenJPA interfaces.
As a result, applications that continue to use Kodo/JPA as the persistence provider with WebLogic Server 12.1.1 must be recompiled. For more information, see "Updating Applications to Overcome Conflicts" in Developing Enterprise JavaBeans for Oracle WebLogic Server
JPA 2.0 Support Using the Default TopLink Persistence Provider – Oracle TopLink, a JPA 2.0 persistence provider, is now the default JPA provider, replacing Kodo, which was the default provider in previous releases. Any application that does not specify a JPA provider in persistence.xml
will now use TopLink by default. Applications can continue to use Kodo (a JPA 1.0 provider) by explicitly specifying Kodo/OpenJPA as their persistence provider in persistence.xml
. In addition, a WebLogic Server domain can be configured to use Kodo by default, if desired.
For more information, see Chapter 8, "Configuring the Persistence Provider in Oracle WebLogic Server."
Applications That Use Kodo as the Persistence Provider – This release of WebLogic Server runs with the JPA 2.0 JAR in the server's classpath. Although JPA 2.0 is upwardly compatible with JPA 1.0, JPA 2.0 introduced some methods to existing JPA interfaces that conflict with existing signatures in OpenJPA interfaces. As a result, applications that continue to use Kodo/JPA as the persistence provider with WebLogic Server 12.1.1 must be recompiled. For more information, see Updating Applications to Overcome Conflicts with JPA 2.0.
The following summarizes the new functionality and simplifications made in EJB 3.0 to the earlier EJB APIs:
You are no longer required to create the EJB deployment descriptor files (such as ejb-jar.xml
). You can now use metadata annotations in the bean file itself to configure metadata. You are still allowed, however, to use XML deployment descriptors if you want; in the case of conflicts, the deployment descriptor value overrides the annotation value.
The only required metadata annotation in your bean file is the one that specifies the type of EJB you are writing (@javax.ejb.Stateless
, @javax.ejb.Stateful
, @javax.ejb.MessageDriven
, or @javax.persistence.Entity
). The default value for all other annotations reflect typical and standard use of EJBs. This reduces the amount of code in your bean file in the case where you are programming a typical EJB; you only need to use additional annotations if the default values do not suit your needs.
The bean file can be a plain old Java object (or POJO); it is no longer required to implement javax.ejb.SessionBean
or javax.ejb.MessageDrivenBean
.
As a result of not having to implement javax.ejb.SessionBean
or javax.ejb.MessageDrivenBean
, the bean file no longer has to implement the lifecycle callback methods, such as ejbCreate
, ejbPassivate
, and so on. If, however, you want to implement these callback methods, you can name them anything you want and then annotate them with the appropriate annotation, such as @javax.ejb.PostActivate
.
Session beans may expose client views via business interfaces. Session beans may either explicitly implement the business interface or they can specify it using the @javax.ejb.Remote
or @javax.ejb.Local
annotations.)
The business interface is a plain old Java interface (or POJI); it should not extend javax.ejb.EJBObject
or javax.ejb.EJBLocalObject
.
The business interface methods may not throw java.rmi.RemoteException
unless the business interface extends java.rmi.Remote
.
Bean files supports dependency injection. Dependency injection is when the EJB container automatically supplies (or injects) a variable or setter method in the bean file with a reference to another EJB or resource or another environment entry in the bean's context.
Bean files support interceptors, which is a standard way of using aspect-oriented programming with EJB.
You can configure two types of interceptor methods: those that intercept business methods and those that intercept lifecycle callbacks.
You can configure multiple interceptor methods that execute in a chain in a particular order.
You can configure default interceptor methods that execute for all EJBs contained in a JAR file.
Because the EJB 3.x programming model is so simple, Oracle no longer supports using the EJBGen tags and code-generating tool on EJB 3.x beans. Rather, you can use this tool only on 2.x beans. For information, see the "EJBGen Reference" in Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.
Enterprise JavaBeans (EJB) 3.1 technology is the server-side component architecture for Java EE 6. EJB 3.1 technology enables rapid and simplified development of distributed, transactional, secure and portable applications based on Java technology.
Session beans implement business logic. There are three types of session beans: stateful, stateless, and singleton. Stateful and stateless session beans serve one client at a time; whereas, singleton session beans can be invoked concurrently.
For detailed information about the types of session beans and when to use them, see "What Is a Session Bean" in the "Enterprise Beans" chapter of the Java EE 6 Tutorial at http://docs.oracle.com/javaee/6/tutorial/doc/gipjg.html
.
Stateful session beans maintain state information that reflects the interaction between the bean and a particular client across methods and transactions. A stateful session bean can manage interactions between a client and other enterprise beans, or manage a workflow.
Example: A company Web site that allows employees to view and update personal profile information could use a stateful session bean to call a variety of other beans to provide the services required by a user, after the user clicks "View my Data" on a page:
Accept the login data from a JSP, and call another EJB whose job it is to validate the login data.
Send confirmation of authorization to the JSP.
Call a bean that accesses profile information for the authorized user.
A stateless session bean does not store session or client state information between invocations—the only state it might contain is not specific to a client, for instance, a cached database connection or a reference to another EJB. At most, a stateless session bean may store state for the duration of a method invocation. When a method completes, state information is not retained.
Any instance of a stateless session bean can serve any client—any instance is equivalent. Stateless session beans can provide better performance than stateful session beans, because each stateless session bean instance can support multiple clients, albeit one at a time. The client of a stateless session bean can be a web service endpoint.
Example: An Internet application that allows visitors to click a "Contact Us" link and send an email could use a stateless session bean to generate the email, based on the "to" and "from" information gathered from the user by a JSP.
Singleton session beans provide a formal programming construct that guarantees a session bean will be instantiated once per application in a particular Java Virtual Machine (JVM), and that it will exist for the life cycle of the application. With singletons, you can easily share state between multiple instances of an enterprise bean component or between multiple enterprise bean components in the application.
Singleton session beans offer similar functionality to stateless session beans but differ from them in that there is only one singleton session bean per application, as opposed to a pool of stateless session beans, any of which may respond to a client request. Like stateless session beans, singleton session beans can implement Web service endpoints. Singleton session beans maintain their state between client invocations but are not required to maintain their state across server crashes or shutdowns.
Example: The Apache Web site provides a "Simple Singleton: ComponentRegistry" example that demonstrates how a singleton bean uses Container-Managed Concurrency to utilize the Read (@Lock(READ))
functionality, to allow multi-threaded access to the bean, and the Write (@Lock(WRITE))
functionality, to enforce single-threaded access to the bean.
A message-driven bean implements loosely coupled or asynchronous business logic in which the response to a request need not be immediate. A message-driven bean receives messages from a JMS Queue or Topic, and performs business logic based on the message contents. It is an asynchronous interface between EJBs and JMS.
Throughout its life cycle, an MDB instance can process messages from multiple clients, although not simultaneously. It does not retain state for a specific client. All instances of a message-driven bean are equivalent—the EJB container can assign a message to any MDB instance. The container can pool these instances to allow streams of messages to be processed concurrently.
The EJB container interacts directly with a message-driven bean—creating bean instances and passing JMS messages to those instances as necessary. The container creates bean instances at deployment time, adding and removing instances during operation based on message traffic.
For detailed information, see Developing Message-Driven Beans for Oracle WebLogic Server.
Example: In an on-line shopping application, where the process of taking an order from a customer results in a process that issues a purchase order to a supplier, the supplier ordering process could be implemented by a message-driven bean. While taking the customer order always results in placing a supplier order, the steps are loosely coupled because it is not necessary to generate the supplier order before confirming the customer order. It is acceptable or beneficial for customer orders to "stack up" before the associated supplier orders are issued.
These sections briefly describe classes required for each bean type, the EJB run-time environment, and the deployment descriptor files that govern a bean's run-time behavior.
Every bean type requires a bean class. Table 2-1 defines the supported client views that make up each type of EJB, and defines any additional required classes.
Note: The EJB 2.1 and earlier API required that Local and Remote clients access the stateful or stateless session bean by means of the session bean's local or remote home and the local or remote component interfaces. These interfaces remain available for use with EJB 3.x; however, the EJB 2.1 Remote and Local client view is not supported for singleton session beans.For more information see "Create EJB Classes and Interfaces" in Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server. |
Table 2-1 Supported Client Views in EJB 3.1
Client Views | Session Bean Types | Additional Required Classes |
---|---|---|
Remote Client |
Stateful, Stateless, and Singleton session beans |
Remote business interface that defines the bean's business and lifecycle methods. |
Local Client |
Stateful, Stateless, and Singleton session beans |
Local business interface that defines the bean's business and lifecycle methods. |
Local No- interface |
Stateful, Stateless, and Singleton session beans |
Only requires the bean class. |
Web Service Clients |
Stateless and Singleton session beans |
A Web service endpoint that is accessed as a JAX-WS or JAX-RPC service endpoint using the JAX-WS or JAX-RPC client view APIs. |
An EJB container is a run-time container for beans that are deployed to an application server. The container is automatically created when the application server starts up, and serves as an interface between a bean and run-time services such as:
Life cycle management
Code generation
Security
Transaction management
Locking and concurrency control
The WebLogic Server EJB 3.1 programming model uses the Java EE 6 metadata annotations feature in which you create an annotated EJB 3.1 bean file, and then compile the class with standard Java compiler, which can then be packaged into a target module for deployment. At runtime, WebLogic Server parses the annotations and applies the required behavioral aspects to the bean file.
For more information, see Programming the Annotated EJB Class.
As of EJB 3.0, you are no longer required to create the EJB deployment descriptor files (such as ejb-jar.xml
). However, you can still use XML deployment descriptors if you want. In the case of conflicts, the deployment descriptor value overrides the annotation value.
If you are continuing to use deployment descriptors in your EJB implementation, refer to "EJB Deployment Descriptors" in Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.
The WebLogic Server EJB container supports three deployment descriptors:
ejb-jar.xml
—The standard Java EE deployment descriptor. The ejb-jar.xml
may be used to define EJBs and to specify standard configuration settings for the EJBs. An ejb-jar.xml
can specify multiple beans that will be deployed together.
weblogic-ejb-jar.xml
—WebLogic Server-specific deployment descriptor that contains elements related to WebLogic Server features such as clustering, caching, and transactions. This file is required if your beans take advantage of WebLogic Server-specific features. Like ejb-jar.xml
, weblogic-ejb-jar.xml
can specify multiple beans that will be deployed together.
weblogic-cmp-jar.xml
—WebLogic Server-specific deployment descriptor that contains elements related to container-managed persistence for entity beans. Entity beans that use container-managed persistence must be specified in a weblogic-cmp-jar.xml
file.
For descriptions of the WebLogic Server EJB deployment descriptors, refer to "Deployment Descriptor Schema and Document Type Definitions Reference" in Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.
An EJB can be accessed by server-side or client-side objects such as servlets, Java client applications, other EJBs, web services, and non-Java clients. Any client of an EJB, whether in the same or a different application, accesses it in a similar fashion. WebLogic Server automatically creates implementations of an EJB's remote home and remote business interfaces, which can function remotely.
Clients access enterprise beans either through a no-interface view or through a business interface. A no-interface view of an enterprise bean exposes the public methods of the enterprise bean implementation class to clients. Clients using the no-interface view of an enterprise bean may invoke any public methods in the enterprise bean implementation class or any super-classes of the implementation class. A business interface is a standard Java programming language interface that contains the business methods of the enterprise bean.
The client of an enterprise bean obtains a reference to an instance of an enterprise bean through either dependency injection, using Java programming language annotations, or JNDI lookup, using the Java Naming and Directory Interface syntax to find the enterprise bean instance.
Dependency injection is the simplest way of obtaining an enterprise bean reference. Clients that run within a Java EE server-managed environment, JavaServer Faces web applications, JAX-RS web services, other enterprise beans, or Java EE application clients, support dependency injection using the javax.ejb.EJB
annotation.
Applications that run outside a Java EE server-managed environment, such as Java SE applications, must perform an explicit lookup. JNDI supports a global syntax for identifying Java EE components to simplify this explicit lookup. For more information see, Using the JNDI Portable Syntax.
Because of network overhead, it is more efficient to access beans from a client on the same machine than from a remote client, and even more efficient if the client is in the same application.
For information on programming client access to an EJB, see "Accessing Enterprise Beans" in the "Enterprise Beans" chapter of the Java EE 6 Tutorial at http://docs.oracle.com/javaee/6/tutorial/doc/gipjg.html
.
WebLogic Server EJBs use:
T3—To communicate with remote objects. T3 is a WebLogic-proprietary remote network protocol that implements the Remote Method Invocation (RMI) protocol.
RMI—To communicate with remote objects. RMI enables an application to obtain a reference to an object located elsewhere in the network, and to invoke methods on that object as though it were co-located with the client on the same JVM locally in the client's virtual machine. An EJB with a remote interface is an RMI object. For more information on WebLogic RMI, see Developing RMI Applications for Oracle WebLogic Server.
HTTP—An EJB can obtain an HTTP connection to a Web server external to the WebLogic Server environment by using the java.net.URL
resource connection factory. For more information, see "Configuring EJBs to Send Requests to an URL" in Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.
You can specify the attributes of the network connection an EJB uses by binding the EJB to a WebLogic Server custom network channel. For more information, see "Configuring Network Resources" in Administering Server Environments for Oracle WebLogic Server.
By default, any user can invoke the public methods of an EJB. Therefore, if you want to restrict access to the EJB, you can use security-related annotations to specify the roles that are allowed to invoke all, or a subset, of the methods, which is explained in Securing Access to the EJB.
In addition, you create security roles and map users to roles using the WebLogic ServeÆ9úr Administration Console to update your security realm. For details, see "Manage Security Roles" in the Oracle WebLogic Server Administration Console Online Help.
For additional information about security and EJBs, see:
"Security Fundamentals" in Understanding Security for Oracle WebLogic Server has introductory information about authentication, authorization and other security topics.
"Securing Enterprise JavaBeans (EJBs)" in Developing Applications with the WebLogic Security Service provides instructions for configuring authentication and authorization for EJBs.
Securing Resources Using Roles and Policies for Oracle WebLogic Server contains instructions for on configuring authentication and authorization for your EJBs using the WebLogic Server Administration Console.
This appendix provides an overview of developing, deploying, and configuring an Oracle Kodo application using WebLogic Server.
Kodo Deprecation Notes: Oracle Kodo JPA/JDO is deprecated in this release. Customers are encouraged to use Oracle TopLink, a JPA 2.0 provider. For more information about Oracle TopLink, see Chapter 8, "Configuring the Persistence Provider in Oracle WebLogic Server." Just as Kodo is deprecated, the Kodo documentation is also deprecated. For current information about using Kodo in WebLogic Server, see Using Oracle Kodo in Oracle WebLogic Server.This release of WebLogic Server runs with the JPA 2.0 JAR in the server's classpath. Although JPA 2.0 is upwardly compatible with JPA 1.0, JPA 2.0 introduced some methods to existing JPA interfaces that conflict with existing signatures in OpenJPA interfaces. As a result, applications that continue to use Kodo/JPA as the persistence provider with WebLogic Server 12.1.1 must be recompiled. For more information, see Updating Applications to Overcome Conflicts with JPA 2.0. Kodo does not support JPA 2.0. Trying to used JPA 2.0 APIs with Kodo in WebLogic Server will produce an error. However, using Kodo as the persistence provider for a specific persistence unit or as the default provider for the domain does not prevent you from using TopLink for a different persistence unit. For more information, see Using Oracle Kodo in Oracle WebLogic Server. |
This appendix includes the following sections:
Oracle Kodo is an implementation of the Java Persistence API (JPA) specification and Java Data Objects (JDO) specification for transparent data objects. Oracle Kodo is available as a stand-alone product and is integrated within WebLogic Server.
This chapter describes how to implement an application using JPA or JDO in WebLogic Server. Within WebLogic Server, the JPA and JDO implementations are part of WebLogic Server's overall Enterprise JavaBean 3.0 persistence implementation.
The first step in implementing a Oracle Kodo application on WebLogic Server is to write the application code. The following resources provide general information on writing an application that uses Oracle Kodo to manage persistence of your data:
Once you are familiar with the steps involved in creating applications using Oracle Kodo and have created your application, the following sections describe how to deploy and configure your application using WebLogic Server.
If you choose to use a different version of Oracle Kodo than the one provided by default within WebLogic Server, you must use the FilteringClassLoader
to specify the packages—in this case Oracle Kodo and OpenJPA— that you want to be loaded from the application, and not from the system classloader.
The following example shows how to load the Oracle Kodo and OpenJPA packages from the application using weblogic-application.xml
:
<prefer-application-packages> <package-name>org.apache.openjpa.*</package-name> <package-name>kodo.*</package-name> </prefer-application-packages>
For more information on filtering classloaders, see "Understanding WebLogic Server Application Classloading" in Developing Applications for Oracle WebLogic Server.
Then, you can package the Oracle Kodo and OpenJPA packages with your application using the library directory, as described in "Library Directories" in Developing Applications for Oracle WebLogic Server.
The following sections describe how to configure persistence.
Oracle Kodo uses two XML files, listed in the following table, to define configuration properties.
Table B-1 Persistence Configuration Files
Configuration File | Description |
---|---|
|
Oracle Kodo configuration parameters defined by the JPA functional specifications. This file is required. The XML schema for structuring this configuration is available at: |
|
Configuration parameters that are specific to Oracle Kodo. This file is not required when deploying an application. If specified, you must still provide a If you do not include The XML schema for structuring this configuration is available at: Note: The |
Edit the contents of the configuration files as required to configure persistence. Persistence units can be packaged as part of a WAR or EJB JAR file, or can be packaged as a JAR file that can be included in a WAR or EAR file. The files should be available as resources in the META-INF
directory of the root of the persistence unit. For container environments, the root of a persistence unit may be one of the following:
EJB-JAR file
WEB-INF/classes
directory of a WAR file
JAR file in the WEB-INF/lib
directory of a WAR file
JAR file in the root of the EAR
JAR file in the EAR library directory
Application client jar file
The following provide considerations for using the configuration files together.
When using the persistence-configuration.xml
file, all Oracle Kodo-specific properties must be included in the persistence-configuration.xml
file and not the persistence.xml
file. In this case, the WebLogic Server Administration Console and WebLogic Scripting Tool (WLST) recognizes the persistence unit as a Oracle Kodo persistence unit and provide advanced configuration and tunables support.
If Oracle Kodo-specific properties are included in the persistence.xml
file, the persistence unit will be treated as a third-party persistence unit by the WebLogic Server Administration Console and WLST.
If the persistence-configuration.xml
descriptor is available and contains an entry for a given persistence unit, then no Oracle Kodo (kodo
) or OpenJPA (openjpa
) properties can be specified in the <properties>
tag of the persistence.xml
file for that persistence unit.
Because Oracle Kodo is a highly customizable environment, many configuration properties relate to the creation and configuration of system plug-ins. Plug-in properties have a syntax very similar to that of Java annotations. They allow you to specify both what class to use for the plug-in and how to configure the public fields or bean properties of the instantiated plug-in instance.
Essentially, plug-ins are defined using a series of properties using name/value pairs. For example, the following shows how a plug-in is defined within persistence.xml
:
<properties> <property name='myplugin.DataCache' value='com.bea.MyDataCache(CacheSize=1000, RemoteHost='CacheServer)'> </properties>
Before you deploy a Oracle Kodo application, you must perform the following tasks:
Create a Oracle Kodo application, as described in Creating an Oracle Kodo Application.
Configure persistence, as described in Configuring Persistence.
Created an archive for your application (.ear
or .war
).
Once completed, you are ready to deploy your application on WebLogic Server. Once your application is configured, an Oracle Kodo application is deployed just like any other application. For complete information on deploying applications, see Deploying Applications to Oracle WebLogic Server.
Note: You cannot create a new persistence unit from the WebLogic Server Administration Console. To create a new persistence unit, you must editpersistence.xml manually. |
Once you have deployed your Oracle Kodo application, you can alter the configuration parameters defined in persistence.xml
and persistence-configuration.xml
.
The following sections describe how to configure a Oracle Kodo application with or without using the WebLogic Server Administration Console.
If your deployed application has defined a persistence unit within persistence.xml
, you can access configuration from within the WebLogic Server Administration Console using the following:
Select Deployments.
Select the name of the module containing a persistence unit that you want to configure.
Select the Configuration tab.
Select the Persistence tab.
From the list of persistence units, select the one that you want to configure.
From here, you can access all of the Oracle Kodo persistence parameters that can be edited from the WebLogic Server Administration Console.
If you need to alter parameters that are not available using the WebLogic Server Administration Console, use one of the following methods:
Manually edit the persistence.xml
and persistence-configuration.xml
files that are archived with the application.
Use the SessionHelper
to access and configure the deployment plan. For more information, see "SessionHelper" in "The Tools Package" in "Understanding the WebLogic Deployment API" in Deploying Applications with the WebLogic Deployment API.
Use the WLST loadApplication()
method to load and update the application deployment plan. For more information, see "Updating the Deployment Plan" in Understanding the WebLogic Scripting Tool.
Manually edit your deployment plan. For more information, see "Manually Customizing the Deployment Plan" in "Exporting an Application for Deployment to New Environments" in Deploying Applications to Oracle WebLogic Server.
This chapter describes how to program the annotated EJB 3.1 class file in WebLogic Server 12.1.3.
This chapter includes the following sections:
The WebLogic Server EJB 3.1 programming model uses the Java EE 6 metadata annotations feature in which you create an annotated EJB 3.1 bean file, compile the class with the standard Java compiler, and the resulting class can then be packaged into a target module for deployment. At runtime, WebLogic Server parses the annotations and applies the required behavioral aspects to the bean file.
Tip: To reduce deployment time, you can also use the WebLogic compile toolweblogic.appc (or its Ant equivalent wlappc ) to pre-compile a deployable archive file, (WAR, JAR, or EAR). Precompiling with weblogic.appc generates certain helper classes and performs validation checks to ensure your application is compliant. |
The annotated 3.1 bean file is the core of your EJB. It contains the Java code that determines how your EJB behaves. The 3.1 bean file is an ordinary Java class file that implements an EJB business interface that outlines the business methods of your EJB. You then annotate the bean file with JDK metadata annotations to specify the shape and characteristics of the EJB, document your EJB, and provide special services such as enhanced business-level security or special business logic during runtime.
See Complete List of Metadata Annotations By Function for a breakdown of the annotations you can specify in a bean file, by function. These annotations include those described by the following specifications:
Enterprise JavaBeans 3.1 Specification (JSR-318) at http://jcp.org/en/jsr/summary?id=318
Common Annotations for the Java Platform (JSR-250) at http://www.jcp.org/en/jsr/detail?id=250
See Appendix A, "EJB Metadata Annotations Reference," for reference information about the annotations, listed in alphabetical order. This topic is part of the iterative development procedure for creating an EJB 3.1, described in Chapter 4, "Iterative Development of Enterprise JavaBeans."
For more information on general EJB design and architecture, see the following documents:
Enterprise JavaBeans web site at http://www.oracle.com/technetwork/java/ejb-141389.html
Introducing the Java EE 6 Platform: Part 3 (EJB Technology, Even Easier to Use) at http://www.oracle.com/technetwork/articles/javaee/javaee6overview-part3-139660.html#ejbeasy
The Java EE 6 Tutorial at http://docs.oracle.com/javaee/6/tutorial/doc/gipjg.html
The requirements for programming the 3.1 bean class file are essentially the same as the 2.x requirements. This section briefly describes the basic mandatory requirements of the bean class, mostly for overview purposes, as well as changes in requirements between 2.x and 3.1.
See Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server for detailed information about the mandatory and optional requirements for programming the bean class.
The following bullets list the 3.1 requirements for programming a bean class, as well as the 2.x requirements that no longer apply:
The class must specify its bean type, typically using one of the following metadata annotations, although you can also override this using a deployment descriptor:
@javax.ejb.Stateless
@javax.ejb.Stateful
@javax.ejb.Singleton
@javax.ejb.MessageDriven
Note: Oracle Kodo JPA/JDO is deprecated in this release. However, if you still using Oracle Kodo, programming a 3.0 entity bean (@javax.ejb.Entity ) is discussed in a separate document.
Customers are encouraged to use Oracle TopLink, which supports JPA 2.0. Kodo supports only JPA 1.0. For more information, see Using Oracle TopLink in Oracle WebLogic Server. |
If the bean is a session bean, the bean class can implement either:
The no-interface local client view type, which simplifies EJB development by providing local session bean access without requiring a separate local business interface.
The bean's business interface(s) or the methods of the bean's business interface(s), if any.
Session beans no longer need to implement javax.ejb.SessionBean
, which means the bean no longer needs to implement the ejbXXX()
methods, such as ejbCreate()
, ejbPassivate()
, and so on.
Stateful session beans no longer need to implement java.io.Serializable
.
Message-driven beans no longer need to implement javax.ejb.MessageDrivenBean
.
The following requirements are the same as in EJB 2.x and are provided only as a brief overview:
The class must be defined as public
, must not be final
, and must not be abstract
. The class must be a top level class.
The class must have a public
constructor that takes no parameters.
The class must not define the finalize()
method.
If the bean is message-driven, the bean class must implement, directly or indirectly, the message listener interface required by the messaging type that it supports or the methods of the message listener interface. In the case of JMS, this is the javax.jms.MessageListener
interface.
The method requirements have not changed since EJB 2.x and are provided in this section for a brief overview only.
The requirements for programming the session bean class' methods (that implement the business interface methods) are as follows:
The method names can be arbitrary.
The business method must be declared as public
and must not be final
or static
.
The argument and return value types for a method must be legal types for RMI/IIOP if the method corresponds to a business method on the session bean's remote business interface or remote interface.
The throws
clause may define arbitrary application exceptions.
The requirements for programming the message-driven bean class' methods are as follows:
The methods must implement the listener methods of the message listener interface.
The methods must be declared as public
and must not be final
or static
.
The sections that follow provide the recommended steps when programming the annotated EJB 3.1 class file.
Specifying the Bean Type (Stateless, Singleton, Stateful, or Message-Driven)
Injecting Resource Dependency into a Variable or Setter Method
Specifying Interceptors for Business Methods or Life Cycle Callback Events
The following procedure describes the typical basic steps when programming the 3.1 bean file for a EJB. The steps you follow depends, of course, on what your EJB does.
Refer to Chapter 3, "Simple Enterprise JavaBeans Examples," for code examples of the topics discussed in the remaining sections.
Import the EJB 3.1 and other common annotations that will be used in your bean file. The general EJB annotations are in the javax.ejb
package, the interceptor annotations are in the javax.interceptor
package, the annotations to invoke a 3.1 entity are in the javax.persistence
package, and the common annotations are in the javax.common
or javax.common.security
packages. For example:
import javax.ejb.Stateless; import javax.ejb.TransactionAttribute; import javax.interceptor.ExcludeDefaultInterceptors;
Specify the interface that your EJB is going to implement, either a business interface or a no-interface view, as well as other standard interfaces. You can either explicitly implement the interface, or use an annotation to specify it.
Use the required annotation to specify the type of bean you are programming (session or message-driven).
See Specifying the Bean Type (Stateless, Singleton, Stateful, or Message-Driven).
Optionally, use dependency injection to use external resources, such as another EJB or other Java EE 6 object.
See Injecting Resource Dependency into a Variable or Setter Method.
Optionally, create an EntityManager
object and use the entity annotations to inject entity information.
Optionally, program and configure business method or life cycle callback method interceptor method. You can program the interceptor methods in the bean file itself, or in a separate Java file.
See Specifying Interceptors for Business Methods or Life Cycle Callback Events.
If your business interface specifies that business methods throw application exceptions, you must program the exception class, the same as in EJB 2.x.
See Programming Application Exceptions for EJB 3.1 specific information.
Optionally, specify the security roles that are allowed to invoke the EJB methods using the security-related metadata annotations.
Optionally, change the default transaction configuration in which the EJB runs.
The EJB 3.x local or remote client of a session bean written to the EJB 3.x API accesses a session bean through its business interface. A local client may also access a session bean through a no-interface view that exposes all public methods of the bean class.
There are two ways you can specify the business interface for the EJB bean class:
By explicitly implementing the business interface, using the implements
Java keyword.
By using metadata annotations (such as javax.ejb.Local
and javax.ejb.Remote
) to specify the business interface. In this case, the bean class does not need to explicitly implement the business interface.
Typically, if an EJB bean class implements an interface, it is assumed to be the business interface of the EJB. Additionally, the business interface is assumed to be the local interface unless you explicitly denote it as the remote interface, either by using the javax.ejb.Remote
annotation or updating the appropriate EJB deployment descriptor. You can specify the javax.ejb.Remote
annotation. as well as the javax.ejb.Local
annotation, in either the business interface itself, or the bean class that implements the interface.
A bean class can have more than one interface. In this case (excluding the interfaces listed below), you must specify the business interface of the EJB by explicitly using the javax.ejb.Local
or javax.ejb.Remote
annotations in either the business interface itself, the bean class that implements the business interface, or the appropriate deployment descriptor.
The following interfaces are excluded when determining whether the bean class has more than one interface:
java.io.Serializable
java.io.Externalizable
Any of the interfaces defined by the javax.ejb
package
The following code snippet shows how to specify the business interface of a bean class by explicitly implementing the interface:
public class ServiceBean implements Service
For the full example, see Example of a Simple Business Interface Stateless EJB.
Client access to an enterprise bean that exposes a local, no-interface view is accomplished through either dependency injection or JNDI lookup.
To obtain a reference to the no-interface view of an enterprise bean through dependency injection, use the javax.ejb.EJB
annotation and specify the enterprise bean's implementation class:
@EJB ExampleBean exampleBean;
To obtain a reference to the no-interface view of an enterprise bean through JNDI lookup, use the javax.naming.InitialContext interface's lookup method:
ExampleBean exampleBean = (ExampleBean) InitialContext.lookup("java:module/ExampleBean");
Clients do not use the new operator to obtain a new instance of an enterprise bean that uses a no-interface view.
There is an example of using the No-interface client view bundled in the WebLogic Server distribution kit. See EJB 3.1: Example of Simplified No-interface Programming and Packaging in a WAR File .
For more detailed information about the implementing the no-interface client view, see "Accessing Local Enterprise Beans Using the No-Interface View" in the "Enterprise Beans" chapter of the Java EE 6 Tutorial at http://docs.oracle.com/javaee/6/tutorial/doc/gipjf.html
.
There is only one required metadata annotation in a 3.1 bean class: an annotation that specifies the type of bean you are programing. You must specify one, and only one, of the following:
@javax.ejb.Stateless
—Specifies that you are programming a stateless session bean.
@javax.ejb.Singleton
—Specifies that you are programming a singleton session bean.
@javax.ejb.Stateful
—Specifies that you are programming a stateful session bean.
@javax.ejb.MessageDriven
—Specifies that you are programming a message-driven bean.
Note: Oracle Kodo JPA/JDO is deprecated in this release. However, if you still using Oracle Kodo, programming a 3.0 entity bean (@javax.ejb.Entity ) is discussed in a separate document.
Customers are encouraged to use Oracle TopLink, which supports JPA 2.0. Kodo supports only JPA 1.0. For more information, see Using Oracle TopLink in Oracle WebLogic Server. |
Although not required, you can specify attributes of the annotations to further describe the bean type. For example, you can set the following attributes for all bean types:
name
—Name of the bean class; the default value is the unqualified bean class name.
mappedName
—Product-specific name of the bean.
description
—Description of what the bean does.
If you are programming a message-driven bean, then you can specify the following optional attributes:
messageListenerInterface
—Specifies the message listener interface, if you haven't explicitly implemented it or if the bean implements additional interfaces.
activationConfig
—Specifies an array of activation configuration name-value pairs that configure the bean in its operational environment.
The following code snippet shows how to specify that a bean is a stateless session bean:
@Stateless public class ServiceBean implements Service
For the full example, see Example of a Simple Business Interface Stateless EJB.
Dependency injection is when the EJB container automatically supplies (or injects) a bean's variable or setter method with a reference to a resource or another environment entry in the bean's context. Dependency injection is simply an easier-to-program alternative to using the javax.ejb.EJBContext
interface or JNDI APIs to look up resources.
You specify dependency injection by annotating a variable or setter method with one of the following annotations, depending on the type of resource you want to inject:
@javax.ejb.EJB
—Specifies a dependency on another EJB.
@javax.annotation.Resource
—Specifies a dependency on an external resource, such as a JDBC datasource or a JMS destination or connection factory.
Note: This annotation is not specific to EJB; rather, it is part of the common set of metadata annotations used by many different types of Java EE components. |
Both annotations have an equivalent grouping annotation to specify a dependency on multiple resources (@javax.ejb.EJBs
and @javax.annotation.Resources
).
Although not required, you can specify attributes to these dependency annotations to explicitly describe the dependent resource. The amount of information you need to specify depends upon its usage context and how much information the EJB container can infer from that context. See javax.ejb.EJB and javax.annotation.Resource for detailed information on the attributes and when you should specify them.
The following code snippet shows how to use the @javax.ejb.EJB
annotation to inject a dependency on an EJB into a variable; only the relevant parts of the bean file are shown:
package examples; import javax.ejb.EJB; ... @Stateful public class AccountBean implements Account { @EJB(beanName="ServiceBean") private Service service; ... public void sayHelloFromAccountBean() { service.sayHelloFromServiceBean(); }
In the preceding example, the private variable service
is annotated with the @javax.ejb.EJB
annotation, which makes reference to the EJB with a bean name of ServiceBean
. The data type of the service variable is Service
, which is the business interface implemented by the ServiceBean
bean class. As soon as the EJB container creates the AccountBean
EJB, the container injects a reference to ServiceBean
into the service
variable; the variable then has direct access to all the business methods of SessionBean
, as shown in the sayHelloFromAccountBean
method implementation in which the sayHelloFromServiceBean
method is invoked.
This section describes how to invoke and update a 3.0 entity from within a session bean.
Note: Oracle TopLink, a JPA 2.0 persistence provider, is now the default JPA provider, replacing Kodo, which was the default provider in previous releases. Any application that does not specify a JPA provider inpersistence.xml will now use TopLink by default. Applications can continue to use Kodo (a JPA 1.0 provider) by explicitly specifying Kodo/OpenJPA as their persistence provider in persistence.xml . In addition, a WebLogic Server domain can be configured to use Kodo by default, if desired. For more information, see Chapter 8, "Configuring the Persistence Provider in Oracle WebLogic Server." |
An entity is a persistent object that represents datastore records; typically an instance of an entity represents a single row of a database table. Entities make it easy to query and update information in a persistent store from within another Java EE component, such as a session bean. A Person
entity, for example, might include name
, address
, and age
fields, each of which correspond to the columns of a table in a database. Using an javax.persistence.EntityManager
object to access and manage the entities, you can easily retrieve a Person
record, based on either their unique id or by using a SQL query, and then change the information and automatically commit the information to the underlying datastore.
The following sections describe the typical programming tasks you perform in your session bean to interact with entities:
In your session bean, use the following metadata annotations inject entity information into a variable:
@javax.persistence.PersistenceContext
—Injects a persistence context into a variable of data type javax.persistence.EntityManager
. A persistence context is simply a set of entities such that, for any persistent identity, there is a unique entity instance. The persistence.xml
file defines and names the persistence contexts available to a session bean.
@javax.persistence.PersistenceContexts
—Specifies a set of multiple persistence contexts.
@javax.persistence.PersistenceUnit
—Injects a persistence context into a variable of data type javax.persistence.EntityManagerFactory
.
@javax.persistence.PersistenceUnits
—Specifies a set of multiple persistence contexts.
The @PersistenceContext
and @PersistenceUnit
annotations perform a similar function: inject persistence context information into a variable; the main difference is the data type of the instance into which you inject the information. If you prefer to have full control over the life cycle of the EntityManager
in your session bean, then use @PersistenceUnit
to inject into an EntityManagerFactory
instance, and then write the code to manually create an EntityManager
and later destroy when you are done, to release resources. If you prefer that the EJB container manage the life cycle of the EntityManager
, then use the @PersistenceContext
annotation to inject directly into an EntityManager
.
The following example shows how to inject a persistence context into the variable em
of data type EntityManager
; relevant code is shown in bold:
package examples; import javax.ejb.Stateless; import javax.persistence.PersistenceContext; import javax.persistence.EntityManager; @Stateless public class ServiceBean implements Service { @PersistenceContext private EntityManager em; ...
Once you have instantiated an EntityManager
object, you can use its methods to interact with the entities in the persistence context. This section discusses the methods used to identify and manage the life cycle of an entity; see Chapter 8, "Using Oracle TopLink in Oracle WebLogic Server." for additional uses of the EntityManager
, such as transaction management, caching, and so on.
Note: For clarity, this section assumes that the entities are configured such that they represent actual rows in a database table. |
Use the EntityManager.find()
method to find a row in a table based on its primary key. The find
method takes two parameters: the entity class that you are querying, such as Person.class
, and the primary key value for the particular row you want to retrieve. Once €ÿyou retrieve the row, you can use standard getXXX
methods to get particular properties of the entity. The following code snippet shows how to retrieve a Person
with whose primary key value is 10
, and then get their address:
public List<Person> findPerson () {
Person p = em.find(Person.class, 10);
Address a = p.getAddress();
Query q = em.createQuery("select p from Person p where p.name = :name");
q.setParameter("name", "Patrick");
List<Person> l = (List<Person>) q.getResultList();
return l;
}
The preceding example also shows how to use the EntityManager.createQuery()
method to create a Query
object that contains a custom SQL query; by contrast, the EntityManager.find()
method allows you to query using only the table's primary key. In the example, the table is queried for all Person
s whose first name is Patrick
; the resulting set of rows populates the List<Person>
object and is returned to the findPerson()
invoker.
To create a new entity instance (and thus add a new row to the database), use the EntityManager.persist
method, as shown in the following code snippet
@TransactionAttribute(REQUIRED) public Person createNewPerson(String name, int age) { Person p = new Person(name, age); em.persist(p); // register the new object with the database Address a = new Address(); p.setAddress(a); em.persist(a); // depending on how things are configured, this may or // may not be required return p; }
Note: Whenever you create or update an entity, you must be in a transaction, which is why the@TransactionAttribute annotation in the preceding example is set to REQUIRED . |
The preceding example shows how to create a new Person, based on parameters passed to the createNewPerson
method, and then call the EntityManager.persist
method to automatically add the row to the database table.
The preceding example also shows how to update the newly-created Person
entity (and thus new table row) with an Address
by using the setAddress()
entity method. Depending on the cascade configuration of the Person
entity, the second persist()
call may not be necessary; this is because the call to the setAddress()
method might have automatically triggered an update to the database. For more information about cascading operations, see Chapter 8, "Using Oracle TopLink in Oracle WebLogic Server."
If you use the EntityManager.find()
method to find an entity instance, and then use a setXXX
method to change a property of the entity, the database is automatically updated and you do not need to explicitly call the EntityManager.persist()
method, as shown in the following code snippet:
@TransactionAttribute(REQUIRED) public Person changePerson(int id, int newAge) { Person p = em.find(Person.class, id); p.setAge(newAge); return p; }
In the preceding example, the call to the Person.setAge()
method automatically triggered an update to the appropriate row in the database table.
Finally, you can use the EntityManager.merge()
method to quickly and easily update a row in the database table based on an update to an entity made by a client, as shown in the following example:
@TransactionAttribute(REQUIRED) public Person applyOfflineChanges(Person pDTO) { return em.merge(pDTO); }
In the example, the applyOfflineChanges()
method is a business method of the session bean that takes as a parameter a Person
, which has been previously created by the session bean client. When you pass this Person
to the EntityManager.merge()
method, the EJB container automatically finds the existing row in the database table and automatically updates the row with the new data. The merge()
method then returns a copy of this updated row.
An interceptor is a method that intercepts a business method invocation or a life cycle callback event. There are two types of interceptors: those that intercept business methods and those that intercept life cycle callback methods.
Interceptors can be specified for session and message-driven beans.
You can program an interceptor method inside the bean class itself, or in a separate interceptor class which you then associate with the bean class with the @javax.interceptor.Interceptors
annotation. You can create multiple interceptor methods that execute as a chain in a particular order.
Interceptor instances may hold state. The life cycle of an interceptor instance is the same as that of the bean instance with which it is associated. Interceptors can invoke JNDI, JDBC, JMS, other enterprise beans, and the EntityManager. Interceptor methods share the JNDI name space of the bean for which they are invoked. Programming restrictions that apply to enterprise bean components to apply to interceptors as well.
Interceptors are configured using metadata annotations in the javax.interceptor
package, as described in later sections.
The following topics discuss how to actually program interceptors for your bean class:
Specifying Business or Life Cycle Interceptors: Typical Steps
Saving State Across Interceptors With the InvocationContext API
The following procedure provides the typical steps to specify and program interceptors for your bean class.
See Example of a Simple Stateful EJB for an example of specifying interceptors and Example of an Interceptor Class for an example of programming an interceptor class.
Decide whether interceptor methods are programmed in bean class or in a separate interceptor class.
If you decide to program the interceptor methods in a separate interceptor class
Program the class, as described in Programming the Interceptor Class.
In your bean class, use the @javax.interceptor.Interceptors
annotation to associate the interceptor class with the bean class. The method in the interceptor class annotated with the @javax.interceptor.AroundInvoke
annotation then becomes a business method interceptor method of the bean class. Similarly, the methods annotated with the life cycle callback annotations become the life cycle callback interceptor methods of the bean class.
You can specify any number of interceptor classes for a given bean class—the order in which they execute is the order in which they are listed in the annotation. If you specify the interceptor class at the class-level, the interceptor methods apply to all appropriate bean class methods. If you specify the interceptor class at the method-level, the interceptor methods apply to only the annotated method.
In the bean class or interceptor class (wherever you are programming the interceptor methods), program business method interceptor methods, as described in Programming Business Method Interceptor Methods.
In the bean class or interceptor class (wherever you are programming the interceptor methods), program life cycle callback interceptor methods, as described in Programming Business Method Interceptor Methods.
In the bean class, optionally annotate methods with the @javax.interceptor.ExcludeClassInterceptors
annotation to exclude any interceptors defined at the class-level.
In the bean class, optionally annotate the class or methods with the @javax.interceptor.ExcludeDefaultInterceptors
annotation to exclude any default interceptors that you might define later. Default interceptors are configured in the ejb-jar.xml
deployment descriptor, and apply to all EJBs in the JAR file, unless you explicitly use the annotation to exclude them.
Optionally specify default interceptors for the entire EJB JAR file, as described in Specifying Default Interceptor Methods.
The interceptor class is a plain Java class that includes the interceptor annotations to specify which methods intercept business methods and which intercept life cycle callback methods.
Interceptor classes support dependency injection, which is performed when the interceptor class instance is created, using the naming context of the associated enterprise bean.
You must include a public no-argument constructor.
You can have any number of methods in the interceptor class, but restrictions apply as to how many methods can be annotated with the interceptor annotations, as described in the following sections.
For an example, see Example of an Interceptor Class.
You specify business method interceptor methods by annotating them with the @AroundInvoke
annotation.
An interceptor class or bean class can have only one method annotated with @AroundInvoke
. To specify that multiple interceptor methods execute for a given business method, you must associate multiple interceptor classes with the bean file, in addition to optionally specifying an interceptor method in the bean file itself. The order in which the interceptor methods execute is the order in which the associated interceptor classes are listed in the @Interceptor
annotation. Interceptor methods in the bean class itself execute after those defined in the interceptor classes.
You cannot annotate a business method itself with the @AroundInvoke
annotation.
The signature of an @AroundInvoke
method must be:
Object <METHOD>(InvocationContext) throws Exception
The method annotated with the @AroundInvoke
annotation must always call InvocationContext.proceed()
or neither the business method will be invoked nor any subsequent @AroundInvoke
methods. See Saving State Across Interceptors With the InvocationContext API for additional information about the InvocationContext
API.
Business method interceptor method invocations occur within the same transaction and security context as the business method for which they are invoked. Business method interceptor methods may throw runtime exceptions or application exceptions that are allowed in the throws
clause of the business method.
For an example, see Example of an Interceptor Class.
Session beans can implement asynchronous methods, business methods where control is returned to the client by the enterprise bean container before the method is invoked on the session bean instance. Clients may then use the Java SE concurrency API to retrieve the result, cancel the invocation, and check for exceptions. Asynchronous methods are typically used for long-running operations, for processor-intensive tasks, for background tasks, to increase application throughput, or to improve application response time if the method invocation result isn't required immediately.
When a session bean client invokes a typical non-asynchronous business method, control is not returned to the client until the method has completed. Clients calling asynchronous methods, however, immediately have control returned to them by the enterprise bean container. This allows the client to perform other tasks while the method invocation completes. If the method returns a result, the result is an implementation of the java.util.concurrent.Future<V>
interface, where â€V†is the result value type. The Future<V>
interface defines methods the client may use to check if the computation is completed, wait for the invocation to complete, retrieve the final result, and cancel the invocation.
Asynchronous method invocation semantics only apply to the no-interface, local business, and remote business client views. Methods exposed through the EJB 2.x local, EJB 2.x remote, and Web service client views must not be designated as asynchronous.
For detailed instructions on creating an asynchronous business method, see "Asynchronous Method Invocation" in the "Enterprise Beans" chapter of the Java EE 6 Tutorial at http://docs.oracle.com/javaee/6/tutorial/doc/gkkqg.html
.
You specify a method to be a life cycle callback interceptor method so that it can receive notification of life cycle events from the EJB container. Life cycle events include creation, passivation, and destruction of the bean instance.
You can name the life cycle callback interceptor method anything you want; this is different from the EJB 2.x programming model in which you had to name the methods ejbCreate()
, ejbPassivate()
, and so on.
You use the following life cycle interceptor annotations to specify that a method is a life cycle callback interceptor method:
@javax.ejb.PrePassivate
—Specifies the method that the EJB container notifies when it is about to passivate a stateful session bean.
@javax.ejb.PostActivate
—Specifies the method that the EJB container notifies right after it has reactivated a stateful session bean.
@javax.annotation.PostConstruct
—Specifies the method that the EJB container notifies before it invokes the first business method and after it has done dependency injection. You typically apply this annotation to the method that performs initialization.
Note: This annotation is in thejavax.annotation package, rather than javax.ejb . |
@javax.annotation.PreDestroy
—Specifies the method that the EJB container notifies right before it destroys the bean instance. You typically apply this annotation to the method that release resources that the bean class has been holding.
Note: This annotation is in thejavax.annotation package, rather than javax.ejb . |
You use the preceding annotations the same way, whether the annotated method is in the bean class or in a separate interceptor class. You can annotate the same method with more than one annotation.
You can also specify any subset or combination of life cycle callback annotations in the bean class or in an associated interceptor class. However, the same callback annotation may not be specified more than once in a given class. If you do specify a callback annotation more than once in a given class, the EJB will not deploy.
To specify that multiple interceptor methods execute for a given life cycle callback event, you must associate multiple interceptor classes with the bean file, in addition to optionally specifying the life cycle callback interceptor method in the bean file itself. The order in which the interceptor methods execute is the order in which the associated classes are listed in the @Interceptor
annotation. Interceptor methods in the bean class itself execute after those defined in the interceptor classes.
The signature of the annotated methods depends on where the method is defined:
Life cycle callback methods defined on a bean class have the following signature:
void <METHOD>()
Life cycle callback methods defined on an interceptor class have the following signature:
void <METHOD>(InvocationContext)
See Saving State Across Interceptors With the InvocationContext API for additional information about the InvocationContext
API.
See javax.ejb.PostActivate, javax.ejb.PrePassivate, javax.annotation.PostConstruct, and javax.annotation.PreDestroy for additional requirements when programming the life cycle interceptor class.
For an example, see Example of an Interceptor Class.
Default interceptor methods apply to all components in a particular EJB JAR file or exploded directory, and thus can only be configured in the ejb-jar.xml
deployment descriptor file and not with metadata annotations, which apply to a particular EJB.
The EJB container invokes default interceptor methods, if any, before all other interceptors defined for an EJB (both business and life cycle). If you do not want the EJB container to invoke the default interceptors for a particular EJB, specify the class-level @javax.interceptor.ExcludeDefaultInterceptors
annotation in the bean file.
In the ejb-jar.xml
file, use the <interceptor-binding>
child element of <assembly-descriptor>
to specify default interceptors. In particular, set the <ejb-name>
child element to *
, which means the class applies to all EJBs, and then the <interceptor-class>
child element to the name of the interceptor class.
The following snippet from an ejb-jar.xml
file shows how to specify the default interceptor class org.mycompany.DefaultIC
:
<?xml version="1.0" encoding="UTF-8"?> <ejb-jar version="3.0" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd"> ... <assembly-descriptor> ... <interceptor-binding> <ejb-name>*</ejb-name> <interceptor-class>org.mycompany.DefaultIC</interceptor-class> </interceptors> </assembly-descriptor> </ejb-jar>
Use the javax.interceptor.InvocationContext
API to pass state information between the interceptors that execute for a given business method or life cycle callback. The EJB Container passes the same InvocationContext
instance to each interceptor method, so you can, for example save information when the first business method interceptor method executes, and then retrieve this information for all subsequent interceptor methods that execute for this business method. The InvocationContext
instance is not shared between business method or life cycle callback invocations.
All interceptor methods must have an InvocationContext
parameter. You can then use the methods of the InvocationContext
interface to get and set context information. The InvocationContext
interface is shown below:
public interface InvocationContext { public Object getBean(); public Method getMethod(); public Object[] getParameters(); public void setParameters(Object[]); public java.util.Map getContextData(); public Object proceed() throws Exception; }
The getBean
method returns the bean instance. The getMethod
method returns the name of the business method for which the interceptor method was invoked; in the case of life cycle callback interceptor methods, getMethod
returns null.
The proceed
method causes the invocation of the next interceptor method in the chain, or the business method itself if called from the last @AroundInvoke
interceptor method.
For an example of using InvocationContext
, see Example of an Interceptor Class.
If you specified in the business interface that a method throws an application method, then you must program the exception as a separate class from the bean class.
Use the @javax.ejb.ApplicationException
annotation to specify that an exception class is an application exception thrown by a business method of the EJB. The EJB container reports the exception directly to the client in the event of the application error.
Use the rollback
Boolean attribute of the @ApplicationException
annotation to specify whether the application error causes the current transaction to be rolled back. By default, the current transaction is not rolled back in event of the error.
You can annotate both checked and unchecked exceptions with this annotation.
The following ProcessingException.java
file shows how to use the @ApplicationException
annotation to specify that an exception class is an application exception thrown by one of the business methods of the EJB:
package examples; import javax.ejb.ApplicationException; /** * Application exception class thrown when there was a processing error * with a business method of the EJB. Annotated with the * @ApplicationException annotation. */ @ApplicationException() public class ProcessingException extends Exception { /** * Catches exceptions without a specified string * */ public ProcessingException() {} /** * Constructs the appropriate exception with the specified string * * @param message Exception message */ public ProcessingException(String message) {super(message);} }
By default, any user can invoke the public methods of an EJB. If you want to restrict access to the EJB, you can use the following security-related annotations to specify the roles that are allowed to invoke all, or a subset, of the methods:
javax.annotation.security.DeclareRoles
—Explicitly lists the security roles that will be used to secure the EJB.
javax.annotation.security.RolesAllowed
—Specifies the security roles that are allowed to invoke all the methods of the EJB (when specified at the class-level) or a particular method (when specified at the method-level.)
javax.annotation.security.DenyAll
—Specifies that the annotated method can not be invoked by any role.
javax.annotation.security.PermitAll
—Specifies that the annotated method can be invoked by all roles.
javax.annotation.security.RunAs
—Specifies the role which runs the EJB. By default, the EJB runs as the user who actually invokes it.
The preceding annotations can be used with many Java EE components that allow metadata annotations, not just EJB 3.1.
You create security roles and map users to roles using the WebLogic Server Administration Console to update your security realm. For details, see "Manage Security Roles" in the Oracle WebLogic Server Administration Console Online Help.
The following example shows a simple stateless session EJB that uses all of the security-related annotations; the code in bold is discussed after the example:
package examples; import javax.ejb.Stateless; import javax.annotation.security.DeclareRoles; import javax.annotation.security.PermitAll; import javax.annotation.security.DenyAll; import javax.annotation.security.RolesAllowed; import javax.annotation.security.RunAs; /** * Bean file that implements the Service business interface. */ @Stateless @DeclareRoles( { "admin", "hr" } ) @RunAs ("admin") public class ServiceBean implements Service { @RolesAllowed ( {"admin", "hr"} ) public void sayHelloRestricted() { System.out.println("Only some roles can invoke this method."); } @DenyAll public void sayHelloSecret() { System.out.println("No one can invoke this method."); } @PermitAll public void sayHelloPublic() { System.out.println("Everyone can invoke this method."); } }
The main points to note about the preceding example are:
Import the security-related metadata annotations:
import javax.annotation.security.DeclareRoles; import javax.annotation.security.PermitAll; import javax.annotation.security.DenyAll; import javax.annotation.security.RolesAllowed; import javax.annotation.security.RunAs;
The class-level @DeclareRoles
annotation explicitly specifies that the admin
and hr
security roles will later be used to secure some or all of the methods. This annotation is not required; any security role referenced in, for example, the @RolesReferenced
annotation is implicitly declared. However, explicitly declaring the security roles makes your code easier to read and understand.
The class-level @RunAs
annotation specifies that, regardless of the user who actually invokes a particular method of the EJB, the EJB container runs the method as the admin
role, assuming, of course, that the original user is allowed to invoke the method.
The @RolesAllowed
annotation on the sayHelloRestricted
method specifies that only users mapped to the admin
and hr
roles are allowed to invoke the method.
The @DenyAll
annotation on the sayHelloSecret
method specifies that no one is allowed to invoke the method.
The @PermitAll
annotation on the sayHelloPublic
method specifies that all users mapped to any roles are allowed to invoke the method.
By default, the EJB container invokes a business method within a transaction context. Additionally, the EJB container itself decides whether to commit or rollback a transaction; this is called container-managed transaction demarcation.
You can change this default behavior by using the following annotations in your bean file:
javax.ejb.TransactionManagement
—Specifies whether the EJB container or the bean file manages the demarcation of transactions. If you specify that the bean file manages it, then you must program transaction management in your bean file, typically using the Java Transaction API (JTA).
javax.ejb.TransactionAttribute
—Specifies whether the EJB container invokes methods within a transaction.
For an example of using the javax.ejb.TransactionAttribute
annotation, see Exampleüp of a Simple Stateful EJB.
The tables in the sections that follow group the annotations based on what task they perform. Appendix A, "EJB Metadata Annotations Reference," provides full reference information about the EJB 3.1 metadata annotations in alphabetical order.
The following summarize the annotations used to specify the bean type.
Table 5-1 Annotations to Specify the Bean Type
Annotation | Description |
---|---|
@javax.ejb.Stateless |
Specifies that the bean class is a stateless session bean. For more information, see javax.ejb.Stateless. |
@javax.ejb.Singleton |
Specifies that the bean class is a singleton session bean. For more information, see javax.ejb.Singleton. |
@javax.ejb.Stateful |
Specifies that the bean class is a stateful session bean. For more information, see javax.ejb.Startup. |
@javax.ejb.Init |
Specifies the correspondence of a stateful session bean class method with a |
@javax.ejb.Remove |
Specifies a remove method of a stateful session bean. For more information, see javax.ejb.Remove. |
@javax.ejb.MessageDriven |
Specifies that the bean class is a message-driven bean. For more information, see javax.ejb.MessageDriven. |
@javax.ejb.ActivationConfigProperty |
Specifies properties used to configure a message-driven bean in its operational environment. For more information, see javax.ejb.ActivationConfigProperty. |
The following summarize the annotations used to specify the local or remote interfaces.
Table 5-2 Annotations to Specify the Local or Remote Interfaces
Annotation | Description |
---|---|
@javax.ejb.Local |
Specifies a local interface of the bean. For more information, see javax.ejb.Local. |
@javax.ejb.Remote |
Specifies a remote interface of the bean. For more information, see javax.ejb.Remote. |
The following summarize the annotations used to support EJB 2.x client view.
Table 5-3 Annotations to Support EJB 2.x Client View
Annotation | Description |
---|---|
@javax.ejb.LocalHome |
Specifies a local home interface of the bean. For more information, see javax.ejb.LocalHome. |
@javax.ejb.RemoteHome |
Specifies a remote home interface of the bean. For more information, see javax.ejb.RemoteHome. |
The following summarize the annotations used to invoke a 3.0 entity bean.
Table 5-4 Annotations to Invoke a 3.0 Entity Bean
Annotation | Description |
---|---|
@javax.persistence.PersistenceContext |
Specifies a dependency on an |
@javax.persistence.PersistenceContexts |
Specifies one or more |
@javax.persistence.PersistenceUnit |
Specifies a dependency on an |
@javax.persistence.PersistenceUnits |
Specifies one or more |
The following summarize the annotations used for transactions.
Table 5-5 Transaction-Related Annotations
Annotation | Description |
---|---|
@javax.ejb.TransactionManagement |
Specifies the transaction management demarcation type (container- or bean-managed). For more information, see javax.ejb.TransactionManagement. |
@javax.ejb.TransactionAttribute |
Specifies whether a business method is invoked within the context of a transaction. For more information, see javax.ejb.TransactionManagement. |
The following summarize the annotations used to specify interceptors.
Table 5-6 Annotations to Specify Interceptors
Annotation | Description |
---|---|
@javax.interceptor.Interceptors |
Specifies the list of interceptor classes associated with a bean class or method. For more information, see javax.interceptor.Interceptors. |
@javax.interceptor.AroundInvoke |
Specifies an interceptor method. For more information, see javax.interceptor.AroundInvoke. |
@javax.interceptor.ExcludeClassInterceptors |
Specifies that, when the annotated method is invoked, the class-level interceptors should not invoke. For more information, see javax.interceptor.ExcludeClassInterceptors. |
@javax.interceptor.ExcludeDefaultInterceptors |
Specifies that, when the annotated method is invoked, the default interceptors should not invoke. For more information, see javax.interceptor.ExcludeDefaultInterceptors. |
The following summarize the annotations used to specify life cycle callbacks.
Table 5-7 Annotations to Specify Life Cycle Callbacks
Annotation | Description |
---|---|
@javax.ejb.PostActivate |
Designates a method to receive a callback after a stateful session bean has been activated. For more information, see javax.ejb.PostActivate. |
@javax.ejb.PrePassivate |
Designates a method to receive a callback before a stateful session bean is passivated. For more information, see javax.ejb.PrePassivate. |
@javax.annotation.PostConstruct |
Specifies the method that needs to be executed after dependency injection is done to perform any initialization. For more information, see javax.annotation.PostConstruct. |
@javax.annotation.PreDestroy |
Specifies a method to be a callback notification to signal that the instance is in the process of being removed by the container. For more information, see javax.annotation.PreDestroy. |
The following metadata annotations are not specific to EJB 3.1, but rather, are general security-related annotations in the javax.annotation.security
package.
Table 5-8 Security-Related Annotations
Annotation | Description |
---|---|
@javax.annotation.security.DeclareRoles |
Specifies the references to security roles in the bean class. For more information, see javax.annotation.security.DeclareRoles. |
@javax.annotation.security.RolesAllowed |
Specifies the list of security roles that are allowed to invoke the bean's business methods. For more information, see javax.annotation.security.RolesAllowed. |
@javax.annotation.security.PermitAll |
Specifies that all security roles are allowed to invoke the method. For more information, see javax.annotation.security.PermitAll. |
@javax.annotation.security.DenyAll |
Specifies that no security roles are allowed to invoke the method. For more information, see javax.annotation.security.DenyAll. |
@javax.annotation.security.RunAs |
Specifies the security role which the method is run as. For more information, see javax.annotation.security.RunAs. |
The following summarize the annotations used for context dependency.
Table 5-9 Context Dependency Annotations
Annotation | Description |
---|---|
@javax.ejb.EJB |
Specifies a dependency to an EJB business interface or home interface. For more information, see javax.ejb.EJB. |
@javax.ejb.EJBs |
Specifies one or more |
@javax.annotation.Resource |
Specifies a dependency on an external resource in the bean's environment. For more information, see javax.annotation.Resource. |
@javax.annotation.Resources |
Specifies one or more |
The following summarize the annotations used for timeout and exceptions.
Table 5-10 Timeout and Exception Annotations
Annotation | Description |
---|---|
@javax.ejb.Timeout |
Specifies the timeout method of the bean class. For more information, see javax.ejb.Timeout. |
@javax.ejb.ApplicationException |
Specifies that an exception is an application exception and should be reported to the client directly. For more information, see javax.ejb.ApplicationException. |
The following summarize the annotations used for timers scheduling-specific annotations.
Table 5-11 Timer and Scheduling Annotations
Annotation | Description |
---|---|
@javax.ejb.Timeout |
Specifies the timeout method of the bean class. For more information, see javax.ejb.Timeout. |
@javax.ejb.ApplicationException |
Specifies that an exception is an application exception and should be reported to the client directly. For more information, see javax.ejb.ApplicationException. |
This chapter describes Oracle TopLink, the default persistence provider in Oracle WebLogic Server 12.1.3, and introduces how to use it. This chapter also tells how to set the default persistence provider in WebLogic Server, how to modify existing Kodo applications for use in the current release, and how to upgrade to a newer version of OpenJPA.
This chapter includes the following sections:
Oracle TopLink is the default persistence provider in WebLogic Server 12c and later. It is a comprehensive standards-based object-persistence and object-transformation framework that provides APIs, schemas, and run-time services for the persistence layer of an application.
The core component of TopLink is the EclipseLink project's produced libraries and utilities. EclipseLink is the open source implementation of the development framework and the runtime provided in TopLink. EclipseLink implements the following specifications, plus value-added extensions:
Java Persistence 2.0 (JPA 2.0).
JPA 2.0 is part of Java Platform, Enterprise Edition 6 (Java EE 6). It includes improvements and enhancements to domain modeling, object/relational mapping, EntityManager
and Query
interfaces, and the Java Persistence Query Language (JPQL). It includes an API for criteria queries, a metamodel API, and support for validation.
For the JPA 2.0 Specification, see "JSR-000317 Java Persistence 2.0" at http://jcp.org/aboutJava/communityprocess/final/jsr317/index.html
.
Java Architecture for XML Binding (JAXB) 2.2. (The EclipseLink JAXB implementation, plus EclipseLink extensions, is called MOXy.)
For the JAXB 2.0 specification, see "JSR-000222 Java Architecture for XML Binding (JAXB) 2.0 " at http://jcp.org/aboutJava/communityprocess/pfd/jsr222/index.html
.
EclipseLink also includes Database Web Service (DBWS), which provides access to relational database artifacts by using a Java API for XML Web Services (JAX-WS) 2 Web service.
EclipseLink also provides support for Oracle Spatial and Oracle XDB mapping.
For more information about EclipseLink, including other supported services, see the EclipseLink project home at http://wiki.eclipse.org/EclipseLink
and the EclipseLink Documentation Center at http://wiki.eclipse.org/EclipseLink/UserGuide
.
In addition to all of EclipseLink, Oracle TopLink includes:
TopLink Grid, an integration between EclipseLink JPA with Oracle Coherence that allows EclipseLink to use Oracle Coherence as a level 2 (L2) cache and persistence layer for entities. For more information, see Developing Applications with Oracle Coherence and Oracle Fusion Middleware Integration Guide for Oracle TopLink with Coherence Grid.
Note: You must have a license for Oracle Coherence to be able to use TopLink Grid. |
Logging integration with WebLogic Server.
MBean support in WebLogic Server.
For information about developing, deploying, and configuring Oracle TopLink applications, see the following:
EclipseLink Documentation Center at http://wiki.eclipse.org/EclipseLink/UserGuide
EclipseLink examples at http://wiki.eclipse.org/EclipseLink/Examples
.
You can specify what persistence provider to use for a persistence unit in the application code or by accepting the default persistence provider set for the WebLogic Server domain, as described in the following sections:
Unless you specify otherwise, TopLink is used as the default persistence provider for a WebLogic Server domain. The default provider is used for any entities in an application that are not configured to use a different persistence provider. The default provider is used for both injected and application-managed entity managers and factories.
You can set the default provider in the WebLogic Server Administration Console or by directly setting JPAMBean.DefaultJPAProvider
. In the WebLogic Server Administration Console, the options are Oracle TopLink or Oracle Kodo.
Note: Oracle Kodo JPA/JDO is deprecated in this release. Customers are encouraged to use Oracle TopLink, which supports JPA 2.0. Kodo supports only JPA 1.0. |
For instructions on setting the default through the WebLogic Server Administration Console, see "Configure the Default JPA Persistence Provider" in Oracle WebLogic Server Administration Console Online Help.
If you change the default provider, you must do the following for any deployed applications that do not specify a JPA provider:
Restart applications that use application-managed entity manager factories.
Redeploy applications that use injected entity manager factories or entity managers.
A persistence provider specified in an application takes precedence over the default provider set for the WebLogic Server domain.
You can set the provider to use in the following ways:
Specify the provider in the <provider>
element for a persistence unit in the persistence.xml
file, for example:
<persistence-unit name="example"> <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider> ... </persistence-unit>
Specify the provider in the javax.persistence.provider
property passed to the Map
parameter of the javax.persistence.Persistence.createEntityManagerFactory(String, Map)
method.
For detailed information about using Oracle TopLink in WebLogic server, see "Using TopLink with WebLogic Server" in Solutions Guide for Oracle TopLink.
When you use Oracle TopLink as the persistence provider in this release of WebLogic Server, you can install a patch that provides support for the Java Persistence Architecture (JPA) 2.1. If you do not apply this patch, JPA 2.0 is supported by default.
Note: Support for JPA 2.1 in WebLogic Server is provided as a patch because JPA 2.1 is part of the Java Platform, Enterprise Edition (Java EE) 7. Therefore, enabling JPA 2.1 support in the current release results in WebLogic Server not meeting all Java EE 6 compatibility requirements. To maintain Java EE 6 compatibility, the files required for JPA 2.1 support are not enabled by default, although they are included in a standard WebLogic Server installation. |
JPA 2.1 includes new support or enhancements for features including Criteria Bulk Update/Delete, stored procedures, JPQL Generic function, injectable entity listeners, TREAT
, converters, DDL generation, and entity graphs. For the complete JPA 2.1 specification, see "JSR-000338 Java Persistence 2.1 (Final Release)" at http://jcp.org/aboutJava/communityprocess/final/jsr338/index.html
.
To use JPA 2.1 in this release of WebLogic Server:
Use Oracle TopLink as the persistence provider, as described in "Using TopLink with WebLogic Server" in Solutions Guide for Oracle TopLink.
Apply the patch, using either of the following methods:
OPatch is a Java-based utility that runs on all supported operating systems and is automatically included with WebLogic Server when you use the generic installer. It is used to apply patches to Oracle software. For information on using OPatch, see Patching with OPatch.
To download the patch that enables JPA 2.1 support, log in to My Oracle Support at http://support.oracle.com/
. Select the Patches and Updates page, and enter the patch number, 17754607, in the search field.
Note: Oracle recommends using OPatch to apply patches to WebLogic Server. However, if you created your WebLogic Server installation with the developer-only installer, which does not include OPatch, you can install the patch manually as described in this section. |
The files required for supporting JPA 2.1 are included with a default WebLogic Server installation, but they are not enabled by default. The files are:
The javax.persistence_2.1.jar
file that contains the JPA 2.1 libraries. This file is installed in the ORACLE_HOME
\oracle_common\modules
directory.
The com.oracle.weblogic.jpa21support_1.0.0.0_2-1.jar
file that contains the files for enabling JPA 2.1 support in WebLogic Server. This file is installed in the WL_HOME
\modules
directory.
You can install the patch manually by putting the files at the start of the WebLogic classpath. For example, you can use either of the following methods:
Define a PRE_CLASSPATH
environment variable before starting WebLogic Server.
For example, in a Windows console window, run the following script before running startWebLogic.cmd
:
@echo off if ".%1" == "." goto TellSyntax set PRE_CLASSPATH=%MW_HOME%\oracle_common\modules\javax.persistence_2.1.jar;%MW_HOME%\wlserver\modules\com.oracle.weblogic.jpa21support_1.0.0.0_2-1.jar goto End :TellSyntax echo setJPA21SupportPatch %MW_HOME%\wlserver\modules :End echo PRE_CLASSPATH=%PRE_CLASSPATH%
A similar script can be written for Linux, UNIX, or Macintosh.
Note: Before running this script, run thesetDomainEnv script, located in the DOMAIN_HOME\bin directory, to make sure that MW_HOME is properly set. |
Modify the commEnv.cmd
or commEnv.sh
script in the WL_HOME
\common\bin
directory and add the PRE_CLASSPATH
at the beginning of the script, setting it to the paths of the JPA 2.1 JAR file and the JPA 2.1 patch.
It is advantageous to use the default Oracle TopLink for your applications, due to its implementation of JPA 2.0, its enhanced set of features, its integration in WebLogic Server, and its integration with TopLink Grid. However, you may want to continue to use Kodo for existing applications that were written for use with Kodo. Although deprecated, Kodo is still included with WebLogic Server: you do not have to install it. You can set it as the default provider, as described in Specifying a Persistence Provider, or configure an application to use it.
Note: Switching an application from one JPA provider to another usually involves more than just flipping a switch. Most obviously, if the application uses proprietary features of the original JPA implementation, that usage will have to change when moving to a different implementation.In addition, differences in the implementations of a standard specification (that is, JPA) can affect the behavior of an application. Although Kodo and TopLink implement their JPA specifications, as do other conforming JPA implementations, each implementation makes its own decisions about unspecified details that can affect the behavior of the application using JPA. When making the switch from one JPA implementation to another, the application should be thoroughly tested with the expectation that some behavioral differences will have to be corrected. |
If you use Kodo, note the information described in the following sections:
You cannot use any JPA 2 APIs with Kodo. Because Kodo supports only JPA 1, trying to use any JPA 2 APIs will generate an error.
The Kodo persistence-configuration.xml
descriptor is valid only when Kodo is the persistence provider. If you include a persistence-configuration.xml
in an application that uses injection and you do not specify Kodo as the persistence provider, the persistence-configuration.xml
descriptor is ignored and a warning is issued.
Kodo is based on open-source OpenJPA 1.x, the JPA 1.0 framework and provider from the Apache Foundation. Although JPA 1.0 is upwardly compatible with JPA 2.0, JPA 2.0 introduced some methods to existing JPA interfaces that conflict with existing signatures in the OpenJPA interfaces used in Kodo. These conflicts arise because the OpenJPA interfaces extend the JPA interfaces that contain the methods that are revised in JPA 2.0.
These conflicts could cause problems with applications that use Kodo as the persistence provider, because the JPA 2.0 jar (rather than the JPA 1.0 jar) is on the WebLogic Server classpath.
To prevent these conflicts, two methods have been changed in the OpenJPA interfaces that ship with Kodo in WebLogic Server 12c and later. The OpenJPA methods that cause the conflict are:
public <T> T OpenJPAEntityManager.detach(T pc)
The above method conflicts with the following JPA 2.0 method in the EntityManager
interface:
public void detach(Object)
public Properties OpenJPAEntityManagerFactory.getProperties()
The above method conflicts with the following JPA 2.0 method in the EntityManagerFactory
interface:
public Map<String, Object> getProperties()
The new signatures are:
public <T> T OpenJPAEntityManager.detachCopy(T pc)
public Map<String, Object> OpenJPAEntityManagerFactory.getProperties()
public Properties OpenJPAEntityManagerFactory.getPropertiesAsProperties()
The first two new signatures follow the changes made in OpenJPA 2.x to address these same conflicts. These signature changes do not alter the semantics of the methods. The getPropertiesAsProperties
method is provided as a convenience to application developers who do not want to accept the different return type of the redesigned getProperties
method. However, the method getPropertiesAsProperties
is not currently in the OpenJPA 2.x interface.
Because of these changes, you should update any applications that use these methods and recompile them with the Kodo OpenJPA 1.0 jar (org.apache.openjpa_
n
.jar
) and the JPA 1 jar (javax.persistence_
n
.jar
) that are shipped with WebLogic Server 12c (or later). This will prevent the old method signatures from being used. After recompiling and deploying, the applications will run without change in behavior.
Applications that use Kodo/JDO are not affected by the conflicts described above. Therefore, you do not have to modify or recompile them.
The current release of OpenJPA from the Apache Foundation supports JPA 2, and you can use it as the persistence provider for applications deployed to WebLogic Server.
Note: OpenJPA is a third-party library that you must plug into WebLogic Server. As such, Oracle support for Oracle WebLogic Server does not include support for the use of OpenJPA. These instructions are provided as a courtesy. |
To use the newer version of OpenJPA, do the following:
Configure a filtering classloader to use the Kodo and OpenJPA classes, as follows:
In a Web application, include the following stanza in the weblogic.xml
file:
<container-descriptor> <prefer-application-packages> <package-name>org.apache.openjpa.*</package-name> </prefer-application-packages> </container-descriptor>
In an enterprise application, include the prefer-application-packages
stanza in weblogic-application.xml
.)
For more information about filtering classloaders, see "Using a Filtering Classloader" in Developing Applications for Oracle WebLogic Server.
Include the OpenJPA jar file in the application's lib
directory. For more information about library directories, see "Library Directories" in Developing Applications for Oracle WebLogic Server.
Configure the application to use OpenJPA (Kodo) as the provider. You cannot simply set Kodo as the domain's default provider in WebLogic Server. You must configure it in the application, as described in Specifying the Persistence Provider in an Application.
Note: This last step applies for any JPA implementation that is packaged with an application. You must specify the implementation to use in the application code and not just accept the default set in WebLogic Server. |