Introduction
The present document approaches the ORM engine of Intershop Commerce Management from the configuration perspective. It is addressed to administrators or DevOps who configure and maintain Intershop Commerce Management instances. This document does not describe the ORM layer implementation. For technical details about the ORM layer, refer to Concept - ORM Layer.
Info
Prior to Intershop version 7.7 the information provided in this document were part of the Administration and Configuration Guide that can be found in the Knowledge Base.
Note
All relevant setup options are to be configured in advance via dedicated deployment script files, before actually executing the deployment. So be aware that if you modify the Intershop Commerce Management configuration after it is deployed, the next deployment will override all changes with the settings specified for your deployment.
The ORM engine is responsible for the object-relational mapping of persistent Java objects to relational database tables. The ORM engine forms an object cache that communicates with the database via JDBC. It consists of multiple sub-systems that perform tasks like loading and parsing deployment descriptors, providing meta-information about persistent objects, generating and executing SQL statements or switching between different transactional and non-transactional states of an object.
The features of the ORM engine include:
- Object-Relational Mapping (inheritance between persistent objects with abstract superclasses, mapping of concrete leaf classes to tables)
- Caching of persistent objects and relations between them
- Transaction handling (begin, commit, rollback, store, object lock)
- JDBC functionality (Oracle JDBC driver)
- Logging of SQL statements and transaction boundaries
Glossary
| Concept | Description |
|---|---|
| ORM | Object-relational mapping (ORM) is a concept to map object-oriented data (e.g., in the form of persistent Java objects) to a relational database schema (e.g., to Oracle tables). |
| ORM engine | The ORM engine forms the persistence layer of Intershop 7/Intershop Commerce Management. In the layered software architecture, the persistent object layer groups the persistent objects, which are used towrite and read data to/from thedatabase. |
| persistent object | Persistent objects (POs) are Java objects used to write and read data to/from the database (ORM beans). They are persistent implementations of business objects. |
References
General Configuration Options
ORM engine settings can be defined globally for the entire cluster, or locally for individual server instances.
- Global settings are stored in the global orm.properties and appserver.properties files, both located in <IS.INSTANCE.SHARE>/system/config/cluster/.
- Local settings for the ORM engine can be stored in the local appserver#.properties files, located in <IS.INSTANCE.LOCAL>/config.
Database Connection Settings
The ORM engine supports three options for connecting to the database:
- Using the JDBC DriverManager
- Using JNDI for connecting to an existing data source defined by the application server
- Creating an own data source using the JDBC Driver
By default, Intershop Commerce Management is set up to create its own data source.
Note
The following settings in the orm.properties file control Intershop Commerce Management's database connection:
# Alternative 1: JDBC DriverManager #intershop.jdbc.driver=[your driver class] #intershop.jdbc.url=[your jdbc url] # Alternative 2: DataSource Lookup via JNDI #intershop.jdbc.dataSourceFactory=\ #com.intershop.beehive.orm.capi.jdbc.JNDIDataSourceFactory #intershop.jdbc.jndiLookupName=beehive:comp/env/jdbc/core/defaultDB #intershop.jndi.contextFactory= #intershop.jndi.providerURL= # Alternative 3: DataSource via JDBC Driver intershop.jdbc.dataSourceFactory=\ com.intershop.beehive.core.capi.jdbc.oracle.OracleUcpDataSourceFactory intershop.jdbc.dataSourceName=defaultDB intershop.jdbc.url=jdbc:oracle:thin:@//<db-hostname>:<db-port>/<db-servicename> intershop.jdbc.driverType=thin intershop.jdbc.networkProtocol=tcp intershop.jdbc.portNumber=<db-port> intershop.jdbc.databaseName=<db-servicename> # common options (used for DataSource via JDBC Driver and Oracle Tools support) intershop.jdbc.serverName=<db-tnsalias> intershop.jdbc.user=<db-user> intershop.jdbc.password=<db-password> # Oracle JDBC Driver properties, see Oracle documentation intershop.jdbc.connectionCacheInitialLimit=5 intershop.jdbc.connectionCacheMinLimit=5 intershop.jdbc.connectionCacheMaxLimit=150 intershop.jdbc.connectionCacheInactivityTimeout=30 # Oracle Real Application Cluster (RAC) - JDBC Fast Connection Failover (FCF) # configuration via: # * Remote Oracle Notification Service (ONS) subscription configuration and # * Client-side daemon "ons.jar" file located within the appserver CLASSPATH. # # Download "ons.jar" from: # * 11gR2: ORACLE_HOME/opmn/lib/ons.jar (database server) # * 12cR1: ORACLE_HOME/opmn/lib/ons.jar (database server) # # Determine Real Application Cluster (RAC) Oracle Notification Services (ONS) ports # contacting your DBA. The following Oracle grid infrastructure tool determines the # remote ONS daemon ports and status on the Oracle RAC nodes: # * 11gR2: onsctl debug # * 12cR1: onsctl debug # Syntax: # intershop.jdbc.rac.fastConnectionFailover=false|true # - enable or disable JDBC FCF, default false. # intershop.jdbc.rac.remoteONSConfig=nodes=host:port[,host:port,...] # - nodes ONS configuration attribute, # a list of host:port pairs separated by comma (,) # Examples two-node RAC cluster or RAC cluster via SCAN: # 1. fastConnectionFailover=true, remoteONSConfig=nodes= # <rac-node1-vip>:6200,<rac-node2-vip>:6200 # 2. fastConnectionFailover=true, remoteONSConfig=nodes=<scan>:6200 # intershop.jdbc.rac.fastConnectionFailover=false intershop.jdbc.rac.remoteONSConfig=nodes=<scan>:6200 # Additional Enfinity settings intershop.jdbc.tablespaces.index=IS_INDX intershop.jdbc.tablespaces.contextIndex=IS_INDX_CTX intershop.jdbc.tablespaces.users=IS_USERS intershop.jdbc.tablespaces.temp=IS_TEMP
Data Source Settings
The following table lists the required settings for connecting to a data source using the JDBC DriverManager.
Property | Description |
|---|---|
intershop.jdbc.driver | Determines the driver class to use when connecting to an existing data source via JDBC. |
intershop.jdbc.url | Specifies the database URL to use when connecting to an existing data source via JDBC. |
The following table lists the required settings for connecting to a data source via JNDI.
Property | Description |
|---|---|
intershop.jdbc.dataSourceFactory | Specifies the JNDI data source factory class to use. |
intershop.jdbc.jndiLookupName | Specifies the JNDI context to which this data source is to be bound. |
intershop.jndi.contextFactory | Determines the context factory class that reads the initial context. |
intershop.jndi.providerURL | Specifies the URL to when connecting to the naming service for the context factory. |
The following table lists the required settings for creating a new data source using the JDBC Driver, Intershop Commerce Management's default option.
Property | Description |
|---|---|
intershop.jdbc.dataSourceFactory | Determines the factory class that creates the JDBC data source instance for the specified database type. |
intershop.jdbc.dataSourceName | Specifies the name of the particular database as specified during the Intershop Commerce Management installation ( |
intershop.jdbc.url | Specifies the database to be contacted. This setting, which is specific for Oracle data sources only, combines some of the database connection parameters mentioned below, such as driver type and database server, into one single URL-like string for convenience. NOTE: Settings made here overwrite those in the single properties. |
intershop.jdbc.driverType | Specifies the type of the database driver. The Intershop Commerce Management standard is thin. |
intershop.jdbc.networkProtocol | Specifies the network protocol used to communicate with the database server. The default is tcp. |
intershop.jdbc.portNumber | Specifies the port number where the database server listens for requests ( |
intershop.jdbc.databaseName | Specifies the name of the particular database as specified during the Intershop Commerce Management installation ( |
UCP Settings
The following table lists the common settings for the Universal Connection Pool (UCP). In the orm.properties file it is necessary that the following properties and values are set. Intershop recommends that you use these settings for this feature as this generally provides for a better performance. For more information about the properties and values, please see Oracle UCP documentation.
Property | Description |
|---|---|
intershop.jdbc.ucp.ConnectionFactoryClassName | Pool data source class= oracle.jdbc.pool.OracleDataSource |
intershop.jdbc.ucp.ConnectionPoolName | Name of the Connection Pool= orm |
intershop.jdbc.ucp.Description | A description Oracle UCP connection pool-enabled data source. |
intershop.jdbc.ucp.RoleName | The role name for the data source |
intershop.jdbc.ucp.DataSourceName | Name of the data source= ${intershop.jdbc.dataSourceName} |
intershop.jdbc.ucp.DatabaseName | Name of the database= ${intershop.jdbc.databaseName} |
intershop.jdbc.ucp.ServerName | Name of the database server= ${intershop.jdbc.serverName} |
intershop.jdbc.ucp.NetworkProtocol | The network protocol= ${intershop.jdbc.networkProtocol} |
intershop.jdbc.ucp.PortNumber | The port number used by the database= ${intershop.jdbc.portNumber} |
The following table lists the data source settings to obtain pooled connections to the database.
Property | Description |
|---|---|
intershop.jdbc.ucp.URL | The URL used to access the database= ${intershop.jdbc.url} |
intershop.jdbc.ucp.User | The username used to access the URL= ${intershop.jdbc.user} |
intershop.jdbc.ucp.Password | The password used to access the URL= ${intershop.jdbc.password} |
The following table lists the database connection attribute settings.
Property | Description |
|---|---|
intershop.jdbc.ucp.InitialPoolSize | The initial number of cached connections allowed= ${intershop.jdbc.connectionCacheInitialLimit} |
intershop.jdbc.ucp.MinPoolSize | The minimum number of cached connections allowed= ${intershop.jdbc.connectionCacheMinLimit} |
intershop.jdbc.ucp.MaxPoolSize | The maximum number of cached connections allowed= ${intershop.jdbc.connectionCacheMaxLimit} |
intershop.jdbc.ucp.InactiveConnectionTimeout | Timeout for stale connections= ${intershop.jdbc.connectionCacheInactivityTimeout} |
intershop.jdbc.ucp.ValidateConnectionOnBorrow | Each connection is checked every time it is acquired. This is commented out by default, but may be useful by some systems. The property |
intershop.jdbc.ucp.MaxStatements | Default value is 10 |
You can view the UCP-enabled data sources information (configuration, general and Fast Connection Failover (FCF) statistics) using the System Management application. Additionally you can perform background monitoring in System Management, by selecting Monitoring > Background > Configurations. Here you can see JDBC connection data, such as available, active and total connections. Refer to Reference - System Monitoring and the System Management online help.
Fast Connection Failover Settings
Intershop Commerce Management can make use of Oracle's Fast Connection Failover (FCF) feature when working with Real Application Cluster (RAC) environments. Generally, Fast Connection Failover manages pooled connections for high availability and provides the following features:
- Rapid detection and cleanup of invalid cached connections,
- Load balancing of available connections,
- Run-time work request distribution to all active Oracle RAC instances.
The following settings in orm.properties control Intershop Commerce Management's FCF usage:
Property | Description |
|---|---|
intershop.jdbc.rac.fastConnectionFailover | Enables (true) or disables (false) the JDBC FCF feature for Intershop Commerce Management |
intershop.jdbc.rac.remoteONSConfig | Lists the Oracle Notification Services (ONS) hosts and ports, or, if applicable, the Single Client Access Name (SCAN) and port |
intershop.jdbc.ucp.FastConnectionFailoverEnabled | Maps to ${intershop.jdbc.rac.fastConnectionFailover} |
intershop.jdbc.ucp.ONSConfiguration | Maps to ${intershop.jdbc.rac.remoteONSConfig} |
The Oracle grid infrastructure tools onsctl and srvctl determine the remote ONS daemon ports, SCAN host or hosts and the status on the Oracle RAC nodes. The following commands, which are to be triggered on the database host, produce the necessary information:
onsctl debug srvctl config scan
Note
DB Connection User/Password Settings
The following settings in orm.properties control the database user and password settings.
Property | Description |
|---|---|
intershop.jdbc.user | Specifies the database user account name as specified during the Intershop Commerce Management installation ( |
intershop.jdbc.password | Specifies the database password as specified during the Intershop Commerce Management installation ( |
intershop.jdbc.password.encrypted | Specifies whether the database password is encrypted ( |
System administrators may want to encrypt the database password, passed and stored as plain text upon installation. Check Recipe: EncryptDatabasePassword how to create an encrypted password.
Miscellaneous DB Connection Settings
The following table lists general settings that are commonly used for the data source lookup, and other database-related Intershop Commerce Management options.
Property | Description |
|---|---|
intershop.jdbc.serverName | Specifies the database server name as specified during the Intershop Commerce Management installation, usually the Oracle TNS name ( |
intershop.jdbc.connectionCacheInitialLimit | Specifies the initial number of connections in the JDBC shared connection pool, that is, the database connections of the Intershop Commerce Management application established via JDBC (default: 5) |
intershop.jdbc.connectionCacheMinLimit | Specifies the minimum number of connections in the JDBC shared connection pool, default: 5 |
intershop.jdbc.connectionCacheMaxLimit | Specifies the maximum number of connections in the JDBC shared connection pool, default: 150 |
intershop.jdbc.connectionCacheInactivityTimeout | Specifies the maximum period (in minutes) a connection can be unused (default: 30). When the period expires, the connection is closed and its resources are freed. |
intershop.jdbc.tablespaces.index | Used by the dbinit process. This property specifies the tablespace name for indexes. The value |
intershop.jdbc.tablespaces.contextIndex | Used by the dbinit process. This property specifies the tablespace name for context indexes. The value |
intershop.jdbc.tablespaces.users | Specifies the tablespace name for users, by default: |
intershop.jdbc.tablespaces.temp | Specifies the tablespace name for temporary data, by default: |
intershop.jdbc.connectionCache*, you can specify additional database connection settings by appending the Oracle property name. Refer to the Oracle documentation for further information.The next table lists general database connection settings that are controlled by the Intershop Commerce Management core cartridge.
Property | Description |
|---|---|
intershop.cartridges.core.jdbc.numberOfSharedReadConnections | Specifies the number of possible shared read connections that are kept beyond the request. This connection pool receives read-only SQL statements that are used, for example, by the Intershop Commerce Management search framework. The default value is 5. |
intershop.cartridges.core.jdbc.maxCachedCursors | Specifies the maximum number of cached database cursors, distributed over the shared read connections. The default value is 25. |
Basic Cache Settings
The properties in the section # Cache Options in appserver.properties define the initial default behavior of the cache service:
intershop.cache.RefreshOnDBInit=true intershop.cache.flushSessionDictionaries=false
intershop.cache.RefreshOnDBInit
Normally, the dbinit import refreshes the PO cache after every import step to update any object dependencies. As there are no import dependencies in a dbinit, you can switch it off by setting this property to false. This accelerates the dbinit considerably.
intershop.cache.flushSessionDictionaries
Specifies whether to delete all session-specific key-value pairs when a cache refresh event is triggered. By default, this option is switched off (false).
PO Cache Synchronization Settings
To synchronize the cache of the applications, Intershop Commerce Management uses event messaging (see Guide - Messaging). The preset default parameter values work for most configurations, but there are a few properties you can set manually if required. The multicast properties (default) listed below are available in the section # Cache Synchronization Settings in orm.properties.
messengerClass, multicastAddress and multicastPort are the only required parameters.#intershop.cacheSync.messengerClass=com.intershop.beehive.messaging.internal.multicast.MulticastMessenger #intershop.cacheSync.multicastAddress=239.1.0.0 #intershop.cacheSync.multicastPort=1111 #intershop.cacheSync.multicastInterface= #intershop.cacheSync.multicastTimeToLive= #intershop.cacheSync.multicastReceiveBufferSize=1048576 #intershop.cacheSync.multicastListenerThreads=5 #intershop.cacheSync.multicastPacketSize=65000
| Property | Description |
|---|---|
intershop.cacheSync.messengerClass | This required setting specifies the messenger class to be used, the default is com.intershop.beehive.messaging.internal.multicast.MulticastMessenger. |
| intershop.cacheSync.multicastAddress | This parameter defines the IP address of the multicast group. The parameter is set to 239.1.0.0 by default. This parameter must be set identically on all machines that are members of the same multicast group, that is, on all machines hosting application servers in the same Intershop Commerce Management cluster. Note Make sure that in your cluster, |
| intershop.cacheSync.multicastPort | Use this parameter to specify the multicast port number. The default value is 1111. This parameter must be set identically on all machines that are members of the same multicast group, that is, on all machines hosting application servers in the same Intershop Commerce Management cluster. Note Make sure that in your cluster, |
| intershop.cacheSync.multicastInterface | If more than one network adapter is available, you can specify the adapter to be used for multicast communication. If this parameter is not set, your system's default adapter is used. |
| ntershop.cacheSync.multicastTimeToLive | This parameter specifies the time-to-live of the multicast packet to control the scope of the multicasts. The default time-to-live value is 1. Increasing the time-to-live value is necessary if the application servers of a cluster belong to different sub-nets that are connected by routers. Note that in this case, the routers must also be configured to pass the IP multicast traffic between the connected application server sub-nets. |
| intershop.cacheSync.multicastReceiveBufferSize | This setting defines the receive buffer size for cache synchronization events. The default value is 1 MB. Consider increasing this value if custom code performs mass data operations through the ORM layer or the number of application servers in the cluster exceeds 10. |
| intershop.cacheSync.multicastListenerThreads | This parameter defines the number of handler threads for cache synchronization events. The default value is 5. Consider increasing this value if custom code performs mass data operations through the ORM layer or the number of application servers in the cluster exceeds 10. |
| intershop.cacheSync.multicastPacketSize | This parameter sets the maximum size of a multicast packet. |
If you intend to use other messaging systems than the default multicast, you must enable and adjust the corresponding intershop.cacheSync properties (see Guide - Messaging).