Configuring the Entity Engine for JIRA
The Entity Engine from the OFBiz project is what JIRA uses to persist data to a database. You can find out more about why we chose the EE at the bottom of this page. See the configuration overview for a conceptual overview of what is being done here.
On this page:
Configuring the Entity Engine for JIRA
The configuration of the Entity Engine is done through an XML file called entityengine.xml. This file is used to define parameters for persistence servers.
For JIRA WAR distributions, this file is located in the edit-webapp/WEB-INF/classes/entityengine.xml subdirectory of the JIRA Installation Directory.
Ensure that your entityengine.xml XML file is well-formed when making changes. Some application server configurations may "swallow" the error messages you should get in your log file if entityengine.xml is not well-formed and instead, report spurious error messages.
Transaction Factory
By default the Entity Engine tries to obtain a JTA transaction factory from the application server using JNDI. The code sample(s) below show the different values for Apache Tomcat application servers.
Tomcat 5.5:
<transaction-factory class="org.ofbiz.core.entity.transaction.JNDIFactory">
<user-transaction-jndi jndi-server-name="default"
jndi-name="java:comp/env/UserTransaction"/>
<transaction-manager-jndi jndi-server-name="default"
jndi-name="java:comp/env/UserTransaction"/>
</transaction-factory>
Altering the Entity Model
The Entity Model describes the table and column layout that JIRA uses in a database. It can be completely altered without changing any of the internal workings of JIRA.
The model provided should work with almost any database (care has been taken to ensure the column and table names are SQL compliant).
The entity model is configured through an XML file called entitymodel.xml (located in the webapp/WEB-INF/classes/entitydefs/entitymodel.xml subdirectory of JIRA WAR distribution's Installation Directory). To edit this file, copy it to the edit-webapp/WEB-INF/classes/entitydefs/entitymodel.xml subdirectory and make changes there. When the WAR is built using build.(sh|bat), the version of the file in the edit-webapp subdirectory will be used.
The format of the file is fairly self explanatory. Essentially, JIRA always refers to the entity-name and field-name attributes within the code. The type attribute of a <field> tag should always match the type attribute of a <field-type-def> tag in your fieldtype-*.xml files.
To change where entities and fields are persisted in your database, simply add or edit the attribute table-name (for entities) or col-name (for fields).
Why we chose the Entity Engine
We chose the EE over CMPorBMPentity beans because:
- it is more portable between application servers
- table schemas are automatically created and updated
- using the field type definitions, we can add support for new databases very quickly
- it is faster than most CMP implementations and has some nice caching features
This document deals with configuring the entity engine for JIRA (but should be applicable to most applications). For more details on the entity engine itself and it's inner workings, see:
- OFBiz Entity Engine Guide describes the theory behind the entity engine, its architecture and usage patterns
- OFBiz Entity Engine configuration guide describes all of the entity engine configuration options, whereas this document just describes configuring the entity engine for JIRA