Identifying and modifying the JPA specification level

Newly created profiles default to the Java Persistence API (JPA) 2.1 specification. You can run AdminTask wsadmin commands to list JPA specifications that are supported by the product and to change the JPA specification that is used by a server, server cluster, or servers that are members of a cluster.

About this task

Avoid trouble: In the Java EE Application Client environment, only the JPA 2.1 specification, using the EclipseLink bundle that is provided by WebSphere® Application Server, is supported.

WebSphere Application Server version 9 supports both the JPA 2.1 and JPA 2.0 specification levels. JPA 2.1 simplifies the management of relational data in applications. You can find information about supported JPA specification levels and JPA providers by using the wsadmin tool or the administrative console. Run the wsadmin AdminTask listSupportedJPASpecifications command to list JPA specification levels and default JPA providers supported by the product. Run the AdminTask showJPASpecLevel command to identify the JPA specification level used by a cluster or server. Run the AdminTask modifyJPASpecLevel command to change the JPA specification level used by a cluster or server.

Starting with WebSphere Application Server Version 9, Eclipselink is provided as a JPA 2.1 provider implementation and is the default persistence provider when JPA 2.1 is configured to be the active specification level. Before version 9, WSJPA, the IBM JPA provider based on Apache OpenJPA, which supports the JPA 2.0 specification, was the default JPA persistence provider. Because JPA providers differ in both behavior and vendor-specific APIs, and OpenJPA is not available as a JPA 2.1 specification implementation, the product provides a JPA 2.0 specification compatibility mode.

The product bundles the following JPA persistence providers:
  • Eclipselink 2.6.x_WAS (default for the JPA 2.1 specification)
  • WSJPA 2.2.x (default for the JPA 2.0 specification)
You can use third-party JPA providers as mandated by the JPA specification. The third-party JPA provider implementation must match the enabled JPA specification level.

Procedure

  • List JPA specification levels supported by the product.

    WebSphere Application Server version 9 supports both JPA 2.1 and JPA 2.0 specification levels. Information about the JPA specification levels and the corresponding providers can be found by using the wsadmin scripting tool or the administrative console.

    1. Start the wsadmin tool.
    2. Run the listSupportedJPASpecifications command to identify the JPA specification levels supported by the current WebSphere Application Server installation. 
      wsadmin>print AdminTask.listSupportedJPASpecifications()
Supported JPA Specification levels are:   
Spec Level   Default JPA Provider    Version   
2.0          OpenJPA                  2.2.x   
2.1          Eclipselink              2.6.x_WAS
      To list only the supported JPA specification level values, use the -versionOnly parameter with a value of true:
      wsadmin>print AdminTask.listSupportedJPASpecifications('[-versionOnly]')
2.0 
2.1
  • Identify the current JPA specification level as configured on a cluster or server.
    The JPA specification level for the target cluster or server can be identified by using the wsadmin scripting tool or the administrative console
    1. Start the wsadmin tool.
    2. Run the AdminTask showJPASpecLevel command.
      The showJPASpecLevel command can take either the node and server name as parameters or it can take an object name that references a cluster or server configuration object.
      Example 1: Targeting a stand-alone server using node and server parameters
      wsadmin>AdminTask.showJPASpecLevel('[-node myNode -server server1]')
2.1
      Example 2: Targeting a standalone server using an object name
      wsadmin>svr = AdminConfig.getid('/Server:server1/')
myCell/nodes/myNode/server/server1|server.xml#Server_1183122130078)
wsadmin>AdminTask.showJPASpecLevel(svr) 
2.1
      Example 3: Targeting a server cluster using an object name 
      wsadmin>svrClstr = AdminConfig.getid('/ServerCluster:AcmeCluster') 
wsadmin>AdminConfig.show(svrClstr, "name")
'[name AcmeCluster]'  

wsadmin>AdminTask.showJPASpecLevel(svrClstr) 
'2.1'
      Example 4: Targeting a server cluster using a cluster's server member:
      wsadmin>svr1 = AdminConfig.getid("/Node:node1/Server:member_node1/") 
wsadmin>AdminConfig.show(svr1, "[name clusterName]") 
'[clusterName AcmeCluster]  
[name member_node1]'  

wsadmin>AdminTask.showJPASpecLevel(svr1) 
'2.1'
  • Modify the selected JPA specification level for a server
    JPA specification level for the target Server can be changed by using the wsadmin tool or the administrative console.
    1. Start the wsadmin tool.
    2. Run the modifyJPASpecLevel command. The AdminTask modifyJPASpecLevel command can take either the node and server name as parameters or it can take an object name that references a server or server cluster configuration object.
      If a server is part of a server cluster, the node and server parameters can be used to address the cluster, affecting all member servers that are associated with the cluster. An additional specLevel parameter is required and accepts values equal to those that are produced by the listSupportedJPASpecifications command.
      Example 1: Targeting a stand-alone server using node and server parameters
      wsadmin>AdminTask.modifyJPASpecLevel('[-node myNode -server server1 -specLevel 2.0]')  
CWWJP8813I: The JPA specification compliance level for Server server1 has been successfully
        set to JPA 2.0. 
      Example 2: Targeting a stand-alone server using an object name
      wsadmin>svr = AdminConfig.getid('/Server:server1/')
server1(cells/myCell/nodes/myNode/server/server1|server.xml#Server_1183122130078
wsadmin>AdminTask.modifyJPASpecLevel(svr, '[ -specLevel 2.0]')
CWWJP8813I: The JPA specification compliance level for Server server1 has been successfully
        set to JPA 2.0.
      Example 3: Targeting a server cluster using an object name
      # svrCluster is a reference to ServerCluster object "AcmeCluster" 
# svr1 is a reference to Server "node1:member_node1", a member of "AcmeCluster" 
# svr2 is a reference to Server "node1:member_node1", a member of "AcmeCluster"
  
wsadmin>AdminTask.showJPASpecLevel(svrClstr) 
'2.1' 
wsadmin>AdminTask.showJPASpecLevel(svr1) 
'2.1'
  
wsadmin>AdminTask.modifyJPASpecLevel(svrClstr, '[ -specLevel 2.0]') 
'CWWJP8813I: The JPA specification compliance level for Cluster AcmeCluster has been successfully set to JPA 2.0.'  

wsadmin>AdminTask.showJPASpecLevel(svrClstr) 
'2.0' 
wsadmin>AdminTask.showJPASpecLevel(svr1) 
'2.0' 
wsadmin>AdminTask.showJPASpecLevel(svr2) 
'2.0'
      Example 4: Targeting a server cluster using a cluster's server member
      # svrCluster is a reference to ServerCluster object "AcmeCluster" 
# svr1 is a reference to Server "node1:member_node1", a member of "AcmeCluster" 
# svr2 is a reference to Server "node1:member_node1", a member of "AcmeCluster"  

wsadmin>AdminTask.showJPASpecLevel(svrClstr) 
'2.1' 
wsadmin>AdminTask.showJPASpecLevel(svr1) 
'2.1' 
wsadmin>AdminTask.showJPASpecLevel(svr2) 
'2.1'  

wsadmin>AdminTask.modifyJPASpecLevel(svr1, '[ -specLevel 2.0]') 
'CWWJP8813I: The JPA specification compliance level for Cluster AcmeCluster has been successfully set to JPA 2.0.'  

wsadmin>AdminTask.showJPASpecLevel(svrClstr) 
'2.0' 
wsadmin>AdminTask.showJPASpecLevel(svr1) 
'2.0' 
wsadmin>AdminTask.showJPASpecLevel(svr2) 
'2.0'
      Note: The modifyJPASpecLevel command does not alter the JPA persistence provider implementation configuration. If you have a JPA persistence provider implementation that is configured and you start the modifyJPASpecLevel command, you will see an informational message that recommends that you verify the JPA persistence provider implementation is valid for the JPA specification level: 
      wsadmin>AdminConfig.create("JavaPersistenceAPIService", svr1, 
[['defaultPersistenceProvider', 
com.acme.jpa.MyJPA21PersistenceProviderImpl']]) 
wsadmin>AdminTask.modifyJPASpecLevel(svr1, '[ -specLevel 2.0]') 
'CWWJP8816I: The JPA specification compliance level for Cluster AcmeCluster has been successfully set to JPA 2.0. Verify that the configured default JPA 
Persistence Provider, com.acme.jpa.MyJPA21PersistenceProviderImpl, is valid for this JPA specification level.'
    3. Save the configuration.
    4. Restart the server for the JPA specification change to take effect.