Changing the default database

Out-of-the-box, OFBiz is integrated with the Apache Derby database system (http://db.apache.org/derby). While Derby is sufficient to handle OFBiz during software development, evaluation, and functional testing, it is not recommended for environments that experience high transaction volumes. In particular, it is not recommended for use in production environments.

Getting ready

Before configuring an external database, the following few steps have to be ensured:

  1. Before changing the OFBiz Entity Engine configuration to use a remote data source, you must first create the remote database; the remote database must exist.

    Note

    Note: if you are not going to install the OFBiz schema and/or seed data on the remote database, but rather intend to use it as is, you will not need to create a database. You will need, however, to define entities for each remote database table you wish to access, and assign those entities to one or more entity groups.

  2. Add a user/owner for the remote database. OFBiz will access the database as this user. Make sure the user has all necessary privileges to create and remove database tables.
  3. Add a user/owner password (if desired or necessary) to the remote database.
  4. Ensure that the IP port the database is listening on for remote connections is open and clear of any firewall obstructions (for example, by default, PostgreSQL listens for connections on port 5432).
  5. Add the appropriate database driver to the ~framework/entity/lib/jdbc directory.

    Note

    For example, if you are using PostgreSQL version 8.3, download the postgresql-8.3-605.jdbc2.jar driver from the PostgreSQL website (http://jdbc.postgresql.org/download.html).

How to do it...

To configure another external database, follow these few steps:

  1. Open the Entity Engine's configuration file located at:
    ~framework/entity/config/entityengine.xml
    
  2. Within the entityengine.xml file, configure the remote database's usage settings. A suggested method for doing this is to take an existing datasource element entry and modify that to reflect the necessary settings for a remote database. There are examples provided for most of the commonly used databases.

    For example, to configure a remote PostgreSQL database with the name of myofbiz_db, with a username ofbiz and password of ofbiz, edit the localpostnew configuration entry as shown here:

    <datasource name="localpostnew"
    helper-class=
    "org.ofbiz.entity.datasource.GenericHelperDAO"
    schema-name="public"
    field-type-name="postnew"
    check-on-start="true"
    add-missing-on-start="true"
    use-fk-initially-deferred="false"
    alias-view-columns="false"
    join-style="ansi"
    result-fetch-size="50"
    use-binary-type-for-blob="true">
    <read-data reader-name="seed"/>
    <read-data reader-name="seed-initial"/>
    <read-data reader-name="demo"/>
    <read-data reader-name="ext"/>
    <inline-jdbc jdbc-driver="org.postgresql.Driver"
    jdbc-uri="jdbc:postgresql://127.0.0.1/myofbiz_db"
    jdbc-username="ofbiz"
    jdbc-password="ofbiz"
    isolation-level="ReadCommitted"
    pool-minsize="2"
    pool-maxsize="250"/>
    </datasource>
    
  3. Configure the default delegator for this data source:
    <delegator name="default" entity-model-reader="main"
    entity-group-reader="main" entity-eca-reader="main"
    distributed-cache-clear-enabled="false">
    <group-map group-name="org.ofbiz"
    datasource-name="localpostnew"/>
    <group-map group-name="org.ofbiz.olap"
    datasource-name="localderbyolap"/>
    </delegator>
    
  4. Save and close the entityengine.xml file.
  5. From the OFBiz install directory, rebuild OFBiz by running the ant run-install command.
  6. Start OFBiz.
  7. Test by observing that the database was created and populated. You may use the WebTools entity reference page (https://localhost:8443/webtools/control/entityref) to search for your newly created entities, or a third-party tool designed to work with your specific database.

How it works...

The Entity Engine is configured using the entityengine.xml file. Whenever OFBiz is restarted, the Entity Engine initializes itself by first referencing this file, and then building and testing all the designated database connections. In this way, an unlimited number of data source connections, database types, and even low-level driver combinations may be applied at runtime without affecting the higher-level database access logic.

By abstracting the connection using one or more delegators, OFBiz further offloads low-level database connection management from the developer, and handles all connection maintenance, data mappings, and the default transaction configuration for an unlimited number of target databases.

To configure one or more database connections, add datasource element declarations with settings as shown here:

datasource element

This element defines one or more database connections.

(Note: some settings are database-specific. Shown here are the default settings for localpostnew, the recommended definition to use for new installations of PostgreSQL).

 

Configuration setting

Usage

helper-class= org.ofbiz.entity.datasource. GenericHelperDAO

The OFBiz utility program (Java class) that performs conversions and other helper functions on behalf of the Entity Engine for this particular database.

field-type-name="postnew"

Pointer to the field type definition XML document that describes the field type mappings for this database. Field type files are found in the ~framework/entity/fieldtype directory. Each file's name is derived by adding the value in this field to a prefix of fieldtype. For example, field type definitions for localpostnew, where the field-type-name ="postnew" are found in: ~framework/entity/fieldtype/fieldtypepostnew.xml

schema-name="public"

Default schema name for PostgreSQL database schemas. Other databases may not require a default schema name. Configure accordingly.

check-on-start="true"

Instructs OFBiz to check the database against the configured data model (that is, against the configured entities for a data source) for missing entities and/or tables.

add-missing-on-start="true"

Instructs OFBiz to add any missing tables and keys to the database based on the defined data model. Set this to false if you do NOT want OFBiz to modify the target database.

use-fk-initially-deferred= "false"

Used to specify whether or not to set the "INITIALLY DEFERRED" option available in many databases when creating foreign keys. (Note: not all databases support this option). When enabled and supported, the foreign keys will not be checked until a transaction is committed.

Defaults to "true".

alias-view-columns="false"

This value is used to compensate for a variation seen in some JDBC drivers where column names returned for aliased fields may be either the alias name or the full text of what makes up that alias name. See your database vendor's documentation for more information on settings per your target database.

Defaults to "true".

join-style="ansi"

Used to specify the syntax to use when doing table joins in view-entity operations. Many databases are adopting the ANSI JOIN standard, but before that was introduced, theta joins were much more common. Two theta join styles are supported: Oracle and MS SQL. Valid values: ansi, ansi-no-parenthesis, theta-oracle or theta-mssql.

Defaults to ansi.

result-fetch-size="50"

Used by OFBiz with the list iterator to determine default result set size.

use-binary-type-for-blob= "true"

Instructs OFBiz on how to map database fields typed as Binary Large Objects (BLOBs).

To specify that the Entity Engine should be connected to a database using a JDBC driver and to configure the specific connection parameters to pass, set the inline-jdbc element attributes as detailed here:

Connection Configuration (inline-jdbc element)

This element configures the database connection.

 

jdbc-driver

Java class file name of the driver to use when accessing the database. This class file must be on the OFBiz CLASSPATH.

jdbc-uri

Network-based location of the database. The syntax for database connection URI(s) vary from database to database. Please refer to your vendor's documentation for the appropriate syntax. For PostgreSQL, the following syntax is used:

jdbc:postgresql://{IP Address}/{Database Name}

jdbc-username

The plain text username as established on the remote database for OFBiz to use to access the database.

jdbc-password

The plain text password as established on the remote database for OFBiz to use when connecting to the database.

isolation-level

Transaction isolation levels determine how insulated concurrently active transactions are from one another. This attribute establishes the default row-level locking behavior for this database connection.

While details of database transaction theory are beyond the scope of this book, it is recommended that most applications should use

ReadCommitted or ReadUncommitted isolation levels.

Note: transactions discussed within the context of the Entity Engine's configuration are not the same transactions as configured for the Service Engine.

pool-size

Used to configure database connection pooling. The provided values are those found by experience to be most useful for the configured data source. The Entity Engine handles all connection acquisition and closure automatically (unless you otherwise instruct it).

pool-maxsize

Used to configure database connection pooling (Minerva). The provided values are those found by experience to be most useful for the configured data source.

See also

Visit http://ofbiz.apache.org/docs/entityconfig.html for more information.

See also your vendor's database documentation.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.139.240.244