Creating a new entity model

The Entity Engine supports an unlimited number of entity definitions spread across an unlimited number of data sources. To create a new entity, sometimes called the entity model, is simply to add the entity's definition to an entity definition file.

Getting ready

Make sure you have an entity definition file defined in an existing ofbiz-component.xml file.

How to do it...

To create a new entity, follow these steps:

  1. Open an existing entity definition file or create a new one.
  2. Add one or more entity elements as shown here. Please note: XML declarations shown below are for demonstration purposes only. Statements have been removed to make reading easier:
    <entity entity-name="EntityName"
package-name="org.ofbiz.somePackageName"
title="My New Entity">
<!-- Entity definition XML declaration(s) go here.
Removed for demonstration purposes -->
</entity>
  3. Each entity element will have one or more of the following declarations added:
    • field element declarations within the entity element:
    <field name="someFieldName" type="any defined type">
</field>
    • prim-key elements to define the primary key for this entity:
    <prim-key field="primaryKeyField"/>
    • relation elements.
  4. Close the entity element with a closing tag (</entity>).
  5. Save and close the file.
  6. Restart OFBiz to make the entity definitions effective.

How it works...

When OFBiz first starts up, it checks the data model as defined by configured entities in valid entity definition files. Any new entries in entity definition files are checked for configuration integrity and added to the OFBiz data model automatically.

There's more...

The following table summarizes many common entity configuration settings:

entity element tag (Required)

  

Attribute name

Required?

Usage

entity-name

Yes

The name used to uniquely identify this entity.

table-name

No

The equivalent database table name. If this value is the same as that of the value specified by the entity-name, then this attribute may be left out of the definition.

package-name

Yes

Used to organize entities. The suggested best practice is to use the org.ofbiz.somepackage syntax, although there are no checks on these values.

To configure one or more primary keys for an entity, add an XML declaration similar to the following:

prim-key element tag (Not required)

It is not required to have a primary key declaration. However, it is highly recommend for both referential integrity and performance improvements. An entity may have an unlimited number of primary key fields defined. Some databases have restrictions on the length of the primary key.

  

Attribute name

Required?

Usage

field

Yes

This is the name of the field.

If performance is an issue, you may optionally configure one or more index elements for an entity. Indexes are configured as shown here:

index element tag (Not required)

  

Attribute name

Required?

Usage

name

Yes

Name to use when using this index.

Note: there is a limit of 18 characters or less for this value.

unique

No

Valid values: true, false

Default: false

index-field element tag

  

name

Yes

The name of the entity field to use as the index.

To configure the following entity behavior for an individual entity, use the settings as shown here:

Configure an XML declaration similar to the following:

Behavior

no-auto-stamp="true"

By default, OFBiz will create the following entity fields: lastUpdatedStamp, lastUpdatedTxStamp, createdStamp, createdTxStamp for all entities. Additionally, these fields are automatically updated as appropriate.

In cases where you are reading and writing to a non-OFBiz database entity, you may want to turn off this behavior.

never-cache="true"

Set this entity to never be cached.

sequence-bank-size= "Integer Value"

Set the range of sequence identifiers used when getting a new sequence identifier using Entity Engine interfaces. The default is "10".

Field elements map the target database columns to the equivalent OFBiz field definition. To add one or more column definitions as field entries, use the field element with the following attribute settings:

field element tag (Required)

Field elements configure one or more columns for the entity.

  

Attribute name

Required?

Usage

name

Yes

This is the name of the field.

col-name

No

If the database table column name is different from the equivalent entity field name, set the value here.

type

Yes

This value may be any supported field type value as defined in the appropriate fieldtype definition file for this database.

encrypt

No

To instruct OFBiz to use its own encryption algorithm to encrypt and decrypt this field's value before storage and upon retrieval, set as true.

Note: setting field encryption in this manner is not the same as using the target database encryption support.

Default: false

enable-audit-log

No

If set to true, the Entity Engine will record any changes to this field in an EntityAuditLog entity.

Default: false

non-null

No

Sets not-null constraints on the database (instead of the field type).

Default: false

Just as physical database tables may be associated with one another through defined "relationships", OFBiz entities may be related. Use the relation element attribute settings to define one or more relational associations between the defined entity and any other OFBiz entities as described here:

relation element tag (Not required)

This element configures one or more relationships for the associated entity. An entity may be related to an unlimited number of other entities using these XML relationship declarations:

  

Attribute name

Required?

Usage

type

Yes

Valid values: one, many, one-nofk

Note: OFBiz automatically creates a foreign key for one-to-one entity relationships. If you don't want a foreign key created, use the one-nofk value.

fk-name

Yes

An "alias" or name to use for this field, when used as a foreign key.

Note: this must be 18 characters or less.

rel-entity-name

Yes

The name of the entity that is the target in this relationship. All relationships are defined from the defined entity to a target entity as specified using the rel-entity-name attribute.

key-map element tag

This element is required if the related entity primary key fields do not have the same name as the entity being defined.

There may be an unlimited number of key-map elements per entity.

  

field-name

Yes

The field name from the defined entity that represents the primary key used in this relationship.

rel-field-name

Yes

The name of the primary key in the related entity used to configure this relationship.

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

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