Document Properties
Kbid
2481M8
Last Modified
23-Apr-2021
Added to KB
26-Jun-2013
Public Access
Everyone
Status
Online
Doc Type
References
Product
  • ICM 7.10
  • ICM 11
Reference - Attributes of Persistent Objects

Native Attributes

Native attributes are persistent attributes which directly map onto columns in the database table represented by a persistent object (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.

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

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:

put methods
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.

get methods
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:

Example of getter and setter method
String getDescription()
Integer setDescription(String aValue)

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.

Note

Some persistent objects do not store their attributes in a separate attribute-value table. They store their (localized) attributes in the same table using a special XML structure instead. This concerns the objects ProductPO, DerivedProductPO and ConfigurationParameterPO. Commonly these objects extend XMLExtensibleObjectPO instead of ExtensibleObjectPO, and they are initiated by the XMLCustomAttributeMgr during server startup. In this case the attribute values are stored in the columns ATTRIBUTES (non-localized) and ATTRIBUTES_<LOCALEID> for each available locale.

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):

set methods (localizable)
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:

put methods (localizable)
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.

Non-Localizable Extensible Object Attributes

Non-localizable attributes are attributes that are meant to have the same value in all locales.

Note

Although non-localizable attributes do not have a locale assigned, they are stored for the lead locale ID in the separate attribute-value table which is associated with the main table of the persistent object. In case a lead locale switch has to be performed, all non-localizable attributes will be updated to the new lead locale by the LocaleInformationPreparer.

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 PO's AttributeValue table. This setting is used for native attributes which should participate in the search mechanisms that operate on AttributeValue tables.

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

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:

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

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.

DCA Access

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

Examples of get and put methods
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.
The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
Home
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to supportadmin@intershop.de if you experience login issues,
or if you want to register as customer.