Guide - ORM Engine Administration

1 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

1.1 Glossary

ConceptDescription
ORMObject-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 engineThe 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 objectPersistent objects (POs) are Java objects used to write and read data to/from the database (ORM beans). They are persistent implementations of business objects.

1.2 References

2 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.

3 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

Do not use the data sources provided by the underlying application server, as this may have a negative impact on performance and stability. It is strongly recommended to use the data source created by Intershop Commerce Management.

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

3.1 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 (<DB.NAME>).

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 (<DB.LISTENER.PORT>).

intershop.jdbc.databaseName

Specifies the name of the particular database as specified during the Intershop Commerce Management installation (<DB.NAME>).

3.2 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 ValidateConnectionOnBorrow administers the process of getting a connection from the pool (synchronized internally in the UCP, i.e., parallel requests are serialized). The connection validation increases latency in regards to database requests. As a result you should carefully consider connections validation and run a performance test before enabling this feature on production systems.

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.

3.3 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

Make sure to contact your DBA to help determine the appropriate RAC, ONS and SCAN information of your database environment if you intend to setup Intershop Commerce Management for FCF.

3.4 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 (<IS.AS.DBCONNECTION.USER>).

intershop.jdbc.password

Specifies the database password as specified during the Intershop Commerce Management installation (<IS.AS.DBCONNECTION.PASSWD>).

intershop.jdbc.password.encrypted

Specifies whether the database password is encrypted (true|false). This property is optional, a missing value means false.

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.

3.5 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 (<IS.AS.DBCONNECTION.TNSALIAS>)

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 IS_INDX is used by the Intershop Commerce Management database initialization. If you connect your Intershop Commerce Management to a different database instance, change this property according to your tablespace name.

intershop.jdbc.tablespaces.contextIndex

Used by the dbinit process. This property specifies the tablespace name for context indexes. The value IS_INDX_CTX is used by the Intershop Commerce Management database initialization. If you connect your Intershop Commerce Management to a different database instance, change this property according to your tablespace name.

intershop.jdbc.tablespaces.users

Specifies the tablespace name for users, by default: IS_USERS.

intershop.jdbc.tablespaces.temp

Specifies the tablespace name for temporary data, by default: IS_TEMP.

Using the syntax 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.

4 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).

5 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.
orm.properties
#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
PropertyDescription

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.multicastAddress is different from intershop.event.multicastAddress.

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.cachSync.port is different from intershop.event.multicastPort.

intershop.cacheSync.multicastInterfaceIf 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.multicastTimeToLiveThis 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.multicastReceiveBufferSizeThis 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.multicastListenerThreadsThis 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.multicastPacketSizeThis 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).

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Tickets