Reference - Attributes of Persistent Objects

1 Native Attributes

Native attributes are persistent attributes which directly map onto columns in the database table represented by a PO. They are part of the object model of the PO. Native attributes are stable, which means that they cannot be created nor can their definition be modified at runtime. Therefore, native attributes are primarily used to model attributes which every instance of a PO is supposed to possess.

Note

Native attributes are not localized. Attributes that are subject to localization have to be modeled as extensible object attributes.

For each native attribute, Intershop Studio creates a pair of attribute accessor methods: a method to read, and a method to set the attribute value (unless the attribute modifier readonly has been set to true, see below). These methods always have the signature:

AttributeType getAttribute() void setAttribute(AttributeType aValue)

where Attribute designates the name of the attribute in the object model, and AttributeType the attribute's data type.

1.1 Data Types and Type Mapping

In Intershop 7, various type conversions are performed for the attributes of persistent objects.

  • The EDL model editor provides a number of elementary types that can be used to model attributes of POs. The types are either standard Java types like Java primitives, custom types contained in the model, or artificial types that are translated during the code generation process into a real Java type.
  • The model types are translated into a Java type that is used in the API of the generated Java class for the PO, e.g., for the attribute's setter and getter methods.
  • In addition, the model types are translated into a JDBC type that is used to store the attribute in the database. The JDBC type is declared in the ORM deployment descriptors.
  • The ORM engine itself provides a mapping of the JDBC types into Oracle types.

The respective mappings for supported data types are listed in the following tables:

Attribute of Primitive Type Mapping:

Model Type

Java Type

JDBC Type

Oracle Type

blob

java.sql.Blob

BLOB

BLOB

boolean

boolean

BOOLEAN

NUMBER(1)

byte

byte

TINYINT

NUMBER(4)

 

byte

BLOB

BLOB

char

char

CHAR

VARCHAR2(3 CHAR)

 

java.lang.String

VARCHAR(*)

VARCHAR2(* CHAR)

clob

java.sql.Clob

CLOB

CLOB

datetime

java.util.Date

TIMESTAMP

TIMESTAMP

decimal

java.math.BigDecimal

DECIMAL

NUMBER(38,6)

double

double

DOUBLE

FLOAT(126)

float

float

FLOAT

FLOAT(63)

int

int

INTEGER

NUMBER(11)

integer

int

INTEGER

NUMBER(11)

long

long

BIGINT

NUMBER(21)

short

short

SMALLINT

NUMBER(6)

text

java.lang.String

CLOB

CLOB

time

java.util.Date

TIMESTAMP

TIMESTAMP

Serializable

java.io.Serializable

BLOB

BLOB

uuid

java.lang.string

VARCHAR(28)

VARCHAR2(28 CHAR)

Attribute of Object Type Mapping:

Model Type

Java Type

JDBC Type

Oracle Type

java.math.BigDecimal

java.math.BigDecimal

DECIMAL

NUMBER(38,6)

java.math.BigInteger

java.math.BigInteger

DECIMAL

NUMBER(38,6)

java.util.Date

java.util.Date

TIMESTAMP

TIMESTAMP

java.io.Serializable

java.io.Serializable

BLOB

BLOB

In addition, there are some complex types that are mapped to artificial names in the object model. The complex types consist of one or more attributes that are mapped again according to their type.

Mapping of Complex Types

Model Type

Java Type

ExchangeRate

com.intershop.beehive.foundation.quantity.ExchangeRate

Money

com.intershop.beehive.foundation.quantity.Money

Quantity

com.intershop.beehive.foundation.quantity.Quantity

ProductRef

com.intershop.beehive.xcs.common.ProductRef

User

com.intershop.beehive.core.capi.user.User

2 Extensible Object Attributes

When modeling a PO, it is often impossible to predict which attributes each particular instance of the PO requires. Moreover, certain attributes may be relevant for a certain subset of PO instances only.
For example, with respect to the CAPI object Product, an attribute like Color may be relevant for clothing, but less relevant for books. Therefore, additional attributes may have to be added to a PO at runtime, depending on the exact usage of the object.
The base class ExtensibleObjectPO provides a wide range of methods to add extensible object attributes at runtime, and to read and modify these attributes and attribute values later on.
Consider the following two methods made available by ExtensibleObjectPO:

void putString(String aName, String aValue)
void putInteger(String aName, Integer aValue)

Calling the first method creates a custom attribute with the first parameter defining the name, e.g., Color, and the second parameter setting the attribute's value, e.g., red. The second method works similarly, except that the attribute is of a different data type.

For each put method, a corresponding get method exists which is used to retrieve the value of an extensible object attribute, passing the attribute name as parameter.

String getString(String aName)
Integer getInteger(String aName)

Besides using these general methods for attributes which are unknown at design time, it is possible to define extensible object attributes directly in the object model. For extensible object attributes defined in the object model, Intershop Studio generates the standard set of getter and setter methods, such as:

String getDescription()
Integer setDescription(String aValue)

2.1 AttributeValue Tables

To store extensible object attributes, each PO based on ExtensibleObjectPO is associated with a special PO implementing com.intershop.beehive.core.capi.domain.AttributeValue.

For example, the PO WarehousePO is associated with the PO WarehousePOAttributeValuePO, which implements AttributeValue.

Note

The associated attribute-value PO is also a persistent object.

WarehousePOAttributeValuePO maps onto a special table storing all extensible object attributes defined for the WarehousePO class.

Each instance of a class derived from AttributeValue represents an attribute of a specific type with a specific value belonging to a specific instance of an ExtensibleObjectPO. Going by example, each custom attribute-value
pair defined for a particular warehouse is stored in its own instance of WarehousePOAttributeValuePO, thus mapping on a particular row in the underlying database table. The Intershop Studio automatically generates the necessary
AttributeValue classes where necessary.

Note

Extensible object attributes are not stored in the database table underlying a particular persistent object. Instead, extensible object attributes are stored in a separate attribute-value table which is associated with the main table of the persistent object.

2.2 Localizable Extensible Object Attributes

Attribute values sometimes have to vary as a function of the locale used. Localizable extensible object attributes provide the necessary mechanism.

Like extensible object attributes, localizable extensible object attribute can be defined directly in the object model. As a consequence, Intershop Studio generates the following set methods (assuming a string attribute description):

void setDescription(String aValue, LocaleInformation aLocale)
void setDescription(String aValue)

The first method allows you to supply a locale along with a value for Description, tying the value to this particular locale. The second method automatically binds the attribute value to the current request locale (if defined) or to the lead locale (fallback). A similar logic applies to the get methods generated by Intershop Studio.

For extensible object attributes not specified in the model, a similar mechanism exists, based on the following methods:

void putString(String aName, String aValue, LocaleInformation aLocale)
void putString(String aName, String aValue)

The first method creates an attribute with a particular name and a particular value specific to a particular locale. The second method creates an attribute-value pair bound to the lead locale.

Note

Localizable extensible object attributes are also always represented as instances of AttributeValue classes.

2.3 Replicated Extensible Object Attributes

Replicated extensible object attributes combine the properties of native attributes and extensible object attributes. This mechanism creates attributes which are generated as part of the PO, and which are replicated inside the POs AttributeValue table. This setting is used for native attributes which should participate in the search mechanisms that operate on AttributeValue tables.

2.4 Data Types

Data types you can use for extensible object attributes include:

  • String
  • Character
  • Int
  • Double
  • Long
  • Boolean
  • BigDecimal
  • Date
  • Quantity
  • Money
  • Text
  • com.intershop.beehive.core.capi.domain.PersistentObject

3 Direct Custom Attributes

Like the extensible object attribute mechanism, direct custom attributes (DCA) provide a way to enhance existing POs with additional attributes. With respect to object-relational mapping, however, direct custom attributes behave much like native attributes. Direct custom attributes are mapped onto core table columns of the PO to which they are added. They are not stored in the associated AttributeValue table. This may increase performance, e.g., when using these attributes as conditions in database queries. Because the attributes are stored directly in the database table underlying a PO, executing a query using these attributes does not necessitate table join operations between the PO's core table and the associated AttributeValue table.

The direct custom attribute mechanism is supported by the Intershop 7 import/export framework.

The following restrictions apply to direct custom attributes:

  • DCAs can only be added to subclasses of ExtensibleObject.
  • DCAs cannot be localized. They are always bound to the lead locale.
  • DCAs cannot be added or modified at runtime. Adding DCAs requires calling an ALTER TABLE statement. The ALTER TABLE statement must consider staging environments.
    The following example of an SQL block adds a column to table BASICPROFILE:

    begin
    staging_ddl.add_column('BASICPROFILE', 'MYCOLUMN', 'VARCHAR2(100CHAR)');
    end;
    /
    

    The first parameter denotes the table name, the second parameter the column name, and the third parameter the column definition. The stored procedure checks internally whether a staging environment exists and calls the required
    commands accordingly. You can execute the SQL block either manually from an SQL console or as part of a script file that is called by the SQLScriptPreparer.

  • DCAs for a particular PO must have unique names. Name conflicts lead to errors during server startup.
  • There is no automatic Oracle context index creation for DCAs. This must be done manually when implementing a cartridge.

3.1 DCA Definition

Direct custom attributes are defined using simple XML-based descriptions. All attribute definitions contributed by a cartridge are declared in the directCustomAttributes.xml descriptor file. The name of the descriptor file is fixed. During cartridge development, the file is located in <IS_SOURCE>/<cartridge_name>/staticfiles/cartridge. When the cartridge is deployed on a system, the file is installed in the directory _<IS_SHARE>/system/cartridges/
<cartridge_name>/release_.

These are all elements involved in configuring direct custom attributes in a directCustomAttributes.xml file:

  • <is_direct_att>
    The root element
  • <entity>
    This element is used to encode all attributes to be added to a particular subclass of ExtensibleObject. Each entity element embeds <projectname>, <classname> and one or more <attribute> definitions.
  • <projectname>
    This tag does not have a special meaning in the current context, but is required for compatibility reasons.
  • <classname>
    Specifies the PO to which a custom attribute is to be added.
  • <attribute>
    Encodes the properties of an attribute to be added to the class specified by the <classname> element of the owning <entity>.
    The following properties are set implicitly.
    • primary-key = false
    • required-attribute = false
    • null-allowed = true
    • optimistic-control = false
  • <attribute-name>
    Defines the name of the attribute.
  • <column-name>(optional)
    Specifies the name of the database column onto which the attribute is mapped. If missing, the attribute name is assumed to be the column name.
  • <type>
    Specifies the data type of the attribute. See the table below for details.
    DCA types and JDBC mapping:

    DCA type

    JDBC type

    boolean

    BOOLEAN

    int

    INTEGER

    long

    BIGINT

    double

    DOUBLE

    java.math.BigDecimal

    DECIMAL

    java.math.BigInteger

    DECIMAL

    java.util.Date

    TIMESTAMP

    text

    CLOB

    Legacy types

    INT

    INTEGER

    DOUBLE

    DOUBLE

    CHAR

    VARCHAR

  • <type-info> (optional)
    Specifies the length of the data type CHAR.

3.2 DCA Access

Direct custom attributes can be accessed using the get and put methods made available by ExtensibleObject, such as:

void putString(String aName, String aValue)
void putInteger(String aName, Integer aValue)
String getString(String aName)
Integer getInteger(String aName)

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
Support Tickets