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.

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:

Attribute of Object Type Mapping:

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

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)

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.

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.

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.

Non-Localizable Extensible Object Attributes

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

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:

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