4 Extending the Data Model
This chapter provides information on how to extend the Oracle Communications Unified Inventory Management (UIM) data model through additions to the metadata. The information describes statically extending the UIM data model, which can result in backward compatibility issues. See "Backward Compatibility" for the implications regarding this type of extension. Another option is to dynamically extend UIM through characteristics. For information about characteristics, see UIM Concepts.
About the UIM Data Model
The UIM data model extends the Oracle Communications Information Model (Information Model). The Information Model is shared by several Oracle Communications products, including UIM. The data model for each product is defined by a collection of XML and XSD files called metadata. Some metadata files are defined by the Information Model, and some metadata files are defined by the product. Regardless of their origin, all metadata files are part of the product installation.
Metadata files define:
-
Tables and columns that comprise the UIM database
-
Entities and attributes that correspond to the tables and columns
-
Enumerated data
-
Life-cycle state transition data
-
Native sequences
-
Tags that govern the definition of an entity, entity manager, enumeration, and native sequence
The metadata files, in conjunction with UIM-provided Ant targets, are used to regenerate the database tables and the corresponding entity Java source files. Another UIM-provided Ant target compiles the entity source files into entity class files and rebuilds the inventory.ear file to include the entity class files.
Note:
The generated entities and compiled source files reside in the inventory.ear file upon installation. The Ant targets for regeneration and compilation are needed only if you statically extend the data model.About Entities
Entities are Java representations of UIM data and are used to persist data in the database. For example, in the UIM database, the TelephoneNumber table defines several columns of data including ID, name, and description, each of which are defined with a data type of String. For each table, there is corresponding Java entity class, such as TelephoneNumber.class, that is compiled from a Java source file, such as TelephoneNumber.java. Each source file defines data attributes with the same names and same data types as the data columns defined for the corresponding table. Each row in the TelephoneNumber table is persisted by an instance of TelephoneNumber.class. The TelephoneNumber table name, column names, and data types correspond directly to TelephoneNumber.java attributes and data types because both are generated from the same entity definition in the metadata.
About Entity Capabilities
A capability is a design pattern that is applied to an entity, such as enabling an entity to be life- cycle managed. For example, an entity that is life-cycle managed progresses through a succession of states during the course of its life. For life-cycle managed entities, UIM tracks two states: administrative state and object state. To support this capability, an entity must define the adminState and objectState attributes. Rather than define these attributes for every entity that supports this pattern, the capability is declared as part of the entity definition. As a result of this declaration, the adminState and objectState attributes are generated for the entity. So, a capability that is declared in an entity definition can result in the generation of attributes, and also the generation of any related entities that support the capability, neither of which are explicitly defined in metadata.
When extending the data model, you can extend existing entities to declare capabilities, or you can create new entities that declare capabilities. See "Understanding Entity Capability Definitions" for more information.
About Entity Relationships
Entity relationships describe how an entity relates to other entities. Entity relationships can be defined as one-to-one, one-to-many, many-to-one, or many-to-many. An entity definition can specify a relationship to an explicitly-defined entity, or to a capability-generated entity.
When extending the data model, you can extend existing entities to define additional relationships, or you can create new entities that define relationships to other entities. See "Understanding Entity Relationship and Collection Definitions" for more information.
About Entity Managers
Entity managers are Java classes that manage a specified set of database tables for a specific functional area. For example, the EquipmentManager class manages the Equipment table, but it also manages other tables in the equipment functional area such as EquipmentHolder, PhysicalPort, PhysicalConnector, and PhysicalDevice.
Entity manager class files are part of UIM and work with the Persistence Framework in managing the UIM database. The metadata defines entity manager interfaces, citing existing entity manager classes in the definition.
When extending the data model, you can extend existing entities to be managed by a specific entity manager, or you can create new entities which requires the creation of new entity managers. See "Understanding Entity Manager Definitions" for more information.
About Entity ID Sequencing
The Oracle database provides a mechanism for obtaining a generated unique number known as a sequence. This mechanism is called an Oracle native sequence. Each UIM entity defines the entityId attribute, which the persistence framework uses to uniquely identify an object. In previous releases, the entityId attribute value was set using just one Oracle native sequence, resulting in the value being a unique number across the entire database. However, this scenario does not provide for optimal processing performance.
To improve processing performance, UIM now defines several additional Oracle native sequences. Each native sequence is given a sequence generator name that is based on a functional area, such as ConnectivitySeqGen, EquipmentSeqGen, and TelephoneNumberSeqGen. The native sequences and corresponding sequence generator names are defined in the metadata, and an entity definition may specify a sequence generator, indicating the native sequence that the entity is to use when setting the entityId attribute value for the entity. For example, the Pipe, PipeTerminiationPoint, and PipeRel entity definitions specify the ConnectivitySeqGen sequence generator. In this scenario, the entityId values for the entities that use a specific native sequence are unique; entityId values are not unique across the entire database.
To keep this information centrally located, all native sequences and their corresponding sequence generator names are defined in the same type of file. Additionally, all entity definitions that specify a sequence generator are extended to specify it in the same type of file. Entity definitions that do not specify a sequence generator name use the default native sequence provided by the database.
Depending on your implementation of UIM, you may determine that you have heavily-used entities that, upon installation, use the default database native sequence. You can extend the data model by extending your heavily-used entity definitions to specify one of the UIM-defined sequence generators. You can also define your own native sequences and corresponding sequence generator names in the metadata, and extend your heavily-used entity definitions to specify one of your new sequence generators. See "Understanding Native Sequence Definitions" for more information.
Note:
The remainder of this chapter refers only to entities and attributes, rather than to tables and columns and corresponding entities and attributes, all of which are generated from entity definitions in the metadata.About the Metadata Files
The metadata files are contained in the UIM_Home/cartridges/tools/ora_uim_entity_sdk_cartproj.zip file. This ZIP file is also located in the UIM SDK. Within the ZIP file, the metadata files are located in the src/uim_poms_lib.jar file unless otherwise noted.
The metadata files include:
File names that start with ocim- indicate that the file is part of the Information Model. These files are common to several Oracle Communications products, including UIM.
File names that start with uim- indicate that the file defines UIM-specific entities, entity attributes, entity managers, enumerations, and transitions.
File names that end with -entities.xml indicate that the file defines entities for a specific area, such as service, equipment, or connectivity. Entities are defined through XML tags that are governed by the package.xsd file and the *-plugin.xsd files, which are described below. Any tags used in an entity definition are a subset of the tags defined in the package.xsd file and the *-plugin.xsd files.
In addition to defining entities, *-entities.xml files also define entity managers, enumerations, and native sequences. The *-entities.xml file content is further explored in "Understanding Entity Definitions".
File names that end with -types.xsd indicate that the file defines entity attributes (name and data type), or inherits entity attributes from a specified entity. For example, the Equipment entity defines several attributes including id, name, and description, all of which are defined as String. In another example, the EquipmentRole entity does not define any attributes; rather, it inherits all of InventoryRole entity attributes. The *-types.xsd file content is further explored in "Understanding Entity Attribute Definitions".
File names that contain -enum- indicate that the file defines either enumeration types or enumeration values. The *-enum-*.* file content is further explored in "Understanding Enumeration Definitions".
*-entityidsequenceextension-entities.xml
File names that end with -entityidsequenceextension-enitities.xml indicate that the file defines native sequences and corresponding sequence generator names, and that it extends both explicitly-defined and capability-generated entities by specifying a sequence generator for the entity to use. The -entityidsequenceextension-enitities.xml file content is further explored in "Understanding Native Sequence Definitions".
File names that end with -transitions.xml indicate that the file defines life-cycle state transitions. The *-transitions.xml file content is further explored in Chapter 5, "Extending Life Cycles".
File names that end with -plugin.xsd indicate that the file defines XML tags that govern definitions in the *-entities.xml files. The *-plugin.xsd files include:
-
uim-plugin.xsd
-
core-plugin.xsd
-
capability-plugin.xsd files, where capability represents a specific capability such as capacity, characteristic, or consumable
The file content of the *-plugin.xsd files is similar to the package.xsd file content. See "package.xsd" for more information.
The uim-plugin.xsd resides in the src/ora_uim_poms.jar file. The core-plugin.xsd file resides in the src/platformFiles/poms/core_poms_lib.jar file.
The capability-plugin.xsd files reside in the correspondingly named src/platformFiles/poms/capability_poms_lib.jar files, where capability represents a specific capability such as capacity, characteristic, or consumable.
The capacity-caps-libs.xml and capacity-model-libs.xml files are internal files that support the modularity of the capability-plugin.xsd files.
The *-libs.xml files reside in the correspondingly named src/platformFiles/poms/capability_poms_lib.jar files, where capability represents a specific capability such as capacity, characteristic, or consumable.
The package.xsd file, and the *-plugin.xsd files, defines XML tags that govern definitions in the *-entities.xml files. For example, <entity>, <implements>, and <relationship> are XML tags used to define an entity, to specify an interface that the entity implements, and to define the entity's relationship to other entities.
The XML tags defined in these files are enforced by the build that generates the database and entities. If an XML tag is added to an *-entities.xml file that is not defined in the package.xsd file or in a *-plugin.xsd file, the build fails with an error citing the invalid XML tag.
There is only package.xsd file and copy of the file resides in each of the src/platformFiles/poms/capability_poms_lib.jar files, where capability represents a specific capability such as capacity, characteristic, or consumable.
Note:
Platform is the base code upon which all Oracle Communications products are built. Platform provides common code used by all Oracle Communications products, including the code that generates and builds the each product's database and entities using the metadata files.The XMLSchema.xsd file defines all the XML tags for the World Wide Web Consortium (W3C). The W3C is the main international standards organization for the World Wide Web.
The XMLSchema.xsd file is industry-standard specific.
Understanding Metadata File Content
The metadata file content defines:
-
Entities
-
Entity attributes
-
Enumerations
-
Native sequences
-
XML tags that govern the definition of an entity, entity manager, enumeration, and native sequence
Understanding Entity Definitions
Entity definitions result in the creation of database tables and corresponding entity source files, which are compiled into entity class files. Entity classes are used to persist data in the database, and each entity class instance mirrors a unique database record in a table.
*-entities.xml Files
Entities are defined by XML elements and attributes that identify various properties of the entity. An entity definition can reside in an ocim-*-entities.xml file, in a uim-*-entities.xml file, or in both files. When an entity definition resides in both files, the UIM portion of the definition extends from the Information Model portion of the definition. For the UIM data model, most entities are defined by both files. There are a handful of entities that are UIM-specific, in which case the entity definition resides only in the uim-*-entities.xml file.
Example of an Entity Defined by Both Files
In the UIM data model, most entity definitions reside in an ocim-*-entities.xml file, with the entity definition extended in a uim-*-entities.xml file, as shown in the following examples. Example 4-1 is an excerpt from the ocim-number-entities.xml file that shows the TelephoneNumber entity definition. The entity definition includes any interfaces the entity implements, any capabilities for which the entity is enabled, and any relationships that the entity has to other entities.
<entity type="ocim:TelephoneNumber"
interface="oracle.communications.inventory.api.entity.TelephoneNumber"
accessControlled="true" entityIdSequenceGenerator="TelephoneNumberSeqGen">
<implements interface=
"oracle.communications.inventory.api.entity.common.NetworkAddress"/>
<attribute name="id" index="true"/>
<attribute name="name" index="true"/>
<!-- **************** Capabilities ******************-->
<lifecycle stateType="ocim:InventoryState"/>
<consumable prefix="TN" attribute="telephoneNumber"
assignmentStateType="ocim:AssignmentState">
<consumer name="ocim:Service" ConfigurationItemEnabled="true"/>
</consumable>
<referenceEnabled prefix="TelephoneNumber" attribute="telephoneNumber"/>
<characteristic spec="ocim:CharacteristicSpecification">
<characteristicName name="ocim:TNCharacteristic"
interface=
"oracle.communications.inventory.api.entity.TNCharacteristic"
table="TN_CHAR"/>
</characteristic>
<businessInteractionEnabled history="true" visibilityState="SHOW"/>
<groupEnabled/>
<!-- **************** Relationships ******************-->
<!-- One-Sided Many-to-One TelephoneNumber to TelephoneNumberSpec -->
<relationship name="specification">
<otherSide type="ocim:TelephoneNumberSpecification"/>
</relationship>
</entity>
Example 4-2 is an excerpt from the uim-number-entities.xml file. The example shows the TelephoneNumber entity definition that extends the TelephoneNumber entity definition from the ocim-number-entites.xml file. In this example, the entity declares an entity manager through the managedBy tag because the entity is business-interaction enabled, as defined in the ocim-number-entities.xml file. Any methods that an entity needs to implement are also defined in the UIM portion of the entity definition.
Example 4-2 Extended Entity Definition
<entity type="ocim:TelephoneNumber"
managedBy="oracle.communications.inventory.api.number.TelephoneNumberManager">
<method name="getDisplayInfo">
<signature><![CDATA[String getDisplayInfo()]]></signature>
<body><![CDATA[
return getName();]]>
</body>
<javadoc>Return an identifiable info String for this resource.</javadoc>
</method>
</entity>
Example of a UIM-Specific Entity Definition
Very few entities are defined by a uim-*-entities.xml file only. One such example is the uim-rule-entities.xml file. Rulesets are UIM-specific functionality, so the Information Model does not define any ruleset entities.
Example 4-3 an is an excerpt from the uim-rule-entities.xml file. The file defines four entities that deal with rulesets. The excerpt shows the ExtensionPoint entity definition, which includes any interfaces the entity implements, any capabilities for which the entity is enabled, and any relationships that the entity has to other entities.
<entity type="ocim:ExtensionPoint"
interface="oracle.communications.inventory.api.entity.ExtensionPoint">
<!-- Two-Sided One-to-Many ExtensionPoint to EnabledExtensionPoint -->
<relationship name="enabledExtensionPoints">
<thisSide inverse="true" collection="java.util.HashSet"/>
<otherSide dependent="true" type="ocim:EnabledExtensionPoint"/>
</relationship>
<!-- Two-Sided One-to-Many ExtensionPoint to ExtensionPointRuleSet -->
<relationship name="extensionPointRuleSets">
<thisSide inverse="true" collection="java.util.HashSet"/>
<otherSide dependent="true" type="ocim:ExtensionPointRuleSet"/>
</relationship>
</entity>
More on Entity Definitions
Entity definitions include capability and relationship declarations. See "Understanding Entity Capability Definitions" and "Understanding Entity Relationship and Collection Definitions" for more information.
The *-entities.xml files also define entity managers. See "Understanding Entity Manager Definitions" for more information.
Understanding Entity Attribute Definitions
Each entity defines a set of attributes in which to store data. Entity attribute definitions result in the creation of database table columns and corresponding entity attributes in source files, which are compiled into entity class files. Entity classes are used to persist data in the database, and each entity class instance mirrors a unique database record in a table.
*-types.xsd Files
Entity attributes are defined by XML elements and attributes that define an attribute's name and data type. Entity attribute definitions reside in *-types.xsd files. Each *-entities.xml file has a corresponding *-types.xsd file. For example, ocim-number-entities.xml and ocim-number-types.xsd, or uim-rule-entities.xml and uim-rule-types.xsd. For each set of corresponding files:
-
The *-entities.xml files define entities and entity managers
-
The *-types.xsd files define entity attributes (name and data type)
Example 4-4 is an excerpt from the ocim-number-types.xsd file that defines the entity attributes (name and data type) for the TelephoneNumber entity. The attribute names defined in the excerpt are id, name, and description, and all of the attribute data types are defined as string.
Example 4-4 Entity Attributes Definition
<xs:complexType name="TelephoneNumber">
<xs:sequence>
<xs:element name="id" type="xs:string">
</xs:element>
<xs:element name="name" type="xs:string">
</xs:element>
<xs:element name="description" type="xs:string">
</xs:element>
.
.
.
</xs:sequence>
</xs:complexType>
Understanding Enumeration Definitions
Enumeration definitions result in attributes that are defined with an enumeration type being limited to storing only previously defined data values. Enumerations are used to regulate data upon which code is based. For example, code can be written to handle a finite number of scenarios based on a finite number of defined enumeration values.
The following *-enum-*.* files are in the metadata:
-
ocim-enum-entities.xml
-
uim-enum-entities.xml
-
ocim-enum-types.xsd
-
uim-enum-types.xsd
*-enum-entities.xml Files
Enumeration types are defined in the ocim-enum-entities.xml and uim-enum-entities.xml files. Example 4-5 is an excerpt from the uim-enum-entities.xml file that shows the definition of two enumeration types: BusinessInteractionState and BusinessInteractionAction.
Example 4-5 Enumeration Type Definition
<enum type="ocim:BusinessInteractionState" enumType="oracle.communications.inventory.api.entity.BusinessInteractionState" adminState="true"/> <enum type="ocim:BusinessInteractionAction" enumType="oracle.communications.inventory.api.entity.BusinessInteractionAction"/>
*-enum-types.xsd Files
Enumeration values are defined in the ocim-enum-types.xsd and uim-enum-types.xsd files. Example 4-6 is an excerpt from the ocim-enum-types.xsd file that shows the definition of two sets of enumeration values. The ocim-enum-entities.xml file and the ocim-enum-types.xsd file both show excerpts of BusinessInteractionState and BusinessInteractionAction. The ocim-enum-entites.xml file defines the enumeration type, and the ocim-enum-types.xsd file defines the enumeration values that are valid for each enumeration type.
Example 4-6 Enumeration Value Definition
<xs:simpleType name="BusinessInteractionState">
<xs:restriction base="xs:string">
<xs:enumeration value="CANCELLED"/>
<xs:enumeration value="COMPLETED"/>
<xs:enumeration value="CREATED"/>
<xs:enumeration value="IN_PROGRESS"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="BusinessInteractionAction">
<xs:restriction base="xs:string">
<xs:enumeration value="CANCEL"/>
<xs:enumeration value="COMPLETE"/>
<xs:enumeration value="PROCESS"/>
<xs:enumeration value="TRANSFER"/>
</xs:restriction>
</xs:simpleType>
Understanding Native Sequence Definitions
Several native sequences and their corresponding sequence generator names are defined in the metadata. Native sequence definitions result in the creation of the native sequence in the database. Several entity definitions are extended to specify a sequence generator, which results in the corresponding native sequence being used to set the entityId attribute value for the entity. The native sequence definitions, their corresponding sequence generator names, and the entity definitions that are extended to specify a sequence generator, reside in the ocim-entityidsequenceextension-entities.xml file.
Note:
Entity definitions that do not specify a native sequence use the default native sequence provided by Platform.ocim-entityidsequenceextension-entities.xml File
Example 4-7 is an excerpt from the ocim-entityidsequenceextension-entities.xml file that shows the definition of three native sequences:
-
ENTITYID_CONNECTIVITY_SEQ
-
ENTITYID_EQUIPMENT_SEQ
-
ENTITYID_TN_SEQ
The corresponding sequence generator names given to these native sequences are:
-
ConnectivitySeqGen
-
EquipmentSeqGen
-
TelephoneNumberSeqGen
Example 4-7 Native Sequence Definition
<entityIdSequenceGenerator name="ConnectivitySeqGen"
sequence="ENTITYID_CONNECTIVITY_SEQ" />
<entityIdSequenceGenerator name="EquipmentSeqGen"
sequence="ENTITYID_EQUIPMENT_SEQ" />
<entityIdSequenceGenerator name="TelephoneNumberSeqGen"
sequence="ENTITYID_TN_SEQ" />
Example 4-8 is an excerpt from the ocim-entityidsequenceextension-entities.xml file that shows the extended definition of three entities to include a sequence generator. In this example, the Pipe, PipeTerminationPoint, and PipeRel entities all specify the ConnectivitySeqGen sequence generator, which results in these entities using the corresponding ENTITYID_CONNECTIVITY_SEQ native sequence to set their respective entityId attribute values.
Example 4-8 Extended Entity Definition
<entity type="ocim:Pipe"
entityIdSequenceGenerator="ConnectivitySeqGen" extension="true"/>
<entity type="ocim:PipeTerminationPoint"
entityIdSequenceGenerator="ConnectivitySeqGen" extension="true"/>
<entity type="ocim:PipeRel"
entityIdSequenceGenerator="ConnectivitySeqGen" extension="true"/>
Note:
See the Persistent Pattern chapter in Oracle Communications Information Model Reference for more information, including a list of entity-to-sequence mappings.Understanding the Tags that Govern Definitions
The package.xsd and *-plugin.xsd files define the tags that govern definitions of entities, entity managers, enumerations, and native sequences in *-entities.xml files.
This section introduces the package.xsd and *-plugin.xsd file content to help you better understand the content when you are viewing it. This section also explains the entity definition's use of the tags to help you better understand how the tags correlate to an entity definition.
Note:
This section does not explain the functionality of the governing tags; it explains where the governing tags are defined and how they are used within the *-entities.xml files.For information on the functionality that the tags provide, see:
-
The documentation for each tag within the package.xsd and *-plugin.xsd files
-
Oracle Communications Information Model Reference
The package.xsd defines the following complexType elements:
-
entity
-
manager
-
enum
-
entityIdSequenceGenerator
The <entity> element defines several elements, and some of the elements define attributes. For example, the <entity> element defines the <import>, <implements>, <attribute>, <relationship>, and <method> elements, as well as several other elements. The <relationship> element defines the join, thisSide, and otherSide attributes. The <entity> element also defines several attributes directly (as opposed to the attributes being defined for an element). For example, the <entity> element defines the interface and managedBy attributes. Within the file, each complexType, element, and attribute is described.
In a similar fashion, the *-plugin.xsd files also define tags that are used in the *-entities.xml files. For example, the capability-*-plugin.xsd files (where capability represents a specific capability such as capacity, characteristic, and consumable) only define tags that are used in an entity definition to declare a particular capability for an entity.
Example 4-9 shows the TelephoneNumber entity definition. The example is numbered so that the information describing the example can be referenced.
01 <entity type="ocim:TelephoneNumber" 02 interface="oracle.communications.inventory.api.entity.TelephoneNumber" 03 accessControlled="true" > 04 <implements interface= 05 "oracle.communications.inventory.api.entity.common.NetworkAddress"/> 06 <attribute name="id" index="true"/> 07 <attribute name="name" index="true"/> 08 <!-- **************** Capabilities ******************--> 09 <lifecycle stateType="ocim:InventoryState"/> 10 <consumable prefix="TN" attribute="telephoneNumber" 11 assignmentStateType="ocim:AssignmentState"> 12 <consumer name="ocim:Service" ConfigurationItemEnabled="true"/> 13 </consumable> 14 <referenceEnabled prefix="TelephoneNumber" attribute="telephoneNumber"/> 15 <characteristic spec="ocim:CharacteristicSpecification"> 16 <characteristicName name="ocim:TNCharacteristic" 17 interface= 18 "oracle.communications.inventory.api.entity.TNCharacteristic" 19 table="TN_CHAR"/> 20 </characteristic> 21 <businessInteractionEnabled history="true" visibilityState="SHOW"/> 22 <groupEnabled/> 23 <!-- **************** Relationships ******************--> 24 <!-- One-Sided Many-to-One TelephoneNumber to TelephoneNumberSpec --> 25 <relationship name="specification"> 26 <otherSide type="ocim:TelephoneNumberSpecification"/> 27 </relationship> 28 </entity>
Lines 01 through 07 define the entity with various tags. For example:
-
Line 01 uses <entity> and type; <entity> is defined as a complexType in package.xsd, and type is defined as an attribute of the <entity> element in package.xsd.
-
Line 02 uses interface, which is defined as an attribute of the <entity> element in package.xsd.
-
Line 03 uses accessControlled, which is defined in the core-plugin.xsd file.
-
Lines 04 and 05 use <implements> and interface; <implements> is defined as an element of the <entity> element in package.xsd, and interface is defined as an attribute of the <implements> element in package.xsd.
-
Lines 06 and 07 use <attribute> and name; <attribute> is defined as a complexType in package.xsd, and name is defined as an attribute of the <attribute> element in package.xsd.
Lines 08 through 22 continue the entity definition by defining the entity's capabilities. For example:
-
Line 09 uses <lifecycle> and stateType, both of which are defined in uim-plugin.xsd.
-
Lines 10 through 13 uses several tags that are defined in consumable-plugin.xsd.
-
Line 14 uses <referenceEnabled>, which is defined in uim-plugin.xsd.
-
Lines 15 through 20 uses several tags that are defined in characteristic-pluginx.xsd.
-
Line 21 uses <businessInteractionEnabled> and visibilityState, both of which are defined in uim-plugin.xsd.
-
Line 22 uses <groupEnabled>, which is defined in groupenabled-plugin.xsd.
Lines 23 through 27 continue the entity definition by defining the entity's relationships to other entities. For example, <relationship>, name, <otherSide>, and type are all defined in package.xsd.
Extending the Data Model Through the Metadata Files
You extend the data model by creating new metadata files.
Caution:
Do not make modifications to the existing metadata files. See "Backward Compatibility" for the issues involved with modifying the existing metadata files.You use Oracle Communications Design Studio to create new metadata files by importing the ora_uim_entity_sdk_cartproj.zip file, and creating new XML or XSD files within the imported project. Any new metadata files you create must reside in the ora_uim_entity_sdk project, within the src directory.
When you define new entities and attributes, or extend existing entities and attributes, the changes are picked up by the Ant target that generates the database and the corresponding entity Java source files. For example, if you add the new entity myNewEntity, myNewEntity is generated as a new table in the database, and MyNewEntity is generated as an entity Java source file. If you add myNewAttribute to an existing entity, myNewAttribute is generated as a new column on the existing table in the database, and myNewAttribute is generated as an attribute within the generated entity Java source file.
The following sections describe extending the data model through the creation of new metadata files.
Defining New Entities
When defining new entities, look at existing *-entities.xml files for examples of how to define various entity properties. The XML tags you use to define a new entity are governed by the package.xsd and *-plugin.xsd files. Be sure to include any referenced schemas in the package statement.
To define a new entity:
-
Create a new XML file.
The file name must end with -entities.xml. For example, myNewFile-entities.xml.
-
Open an existing *-entities.xml file.
-
Copy and paste an entity definition from the existing file to your new file.
-
Modify the copied entity definition as needed:
-
Change the name of the entity to reflect the name of your new entity.
-
Remove or update the tags to reflect the definition of your new entity.
-
-
Write an entity manager that defines the interfaces to manage the new entity. See "Creating New Entity Managers".
-
Write an entity manager implementation that inherits from BaseInvManager and defines the methods to manage the new entity. See "Creating New Entity Managers".
-
Include the entity manager interface definition in your new *-entities.xml file.
Creating New Entity Managers
When creating new entity managers, the entity managers:
-
Should provide coarse-grained methods that may involve other entity managers
-
Assume that the caller is managing transaction boundaries
-
Must be developed so that they are stateless and thread safe so they can be exposed to web service calls
-
Should avoid creating duplicate records using makePersistent(). To avoid this, call the connect() method before you set entities to the transient state. See "PersistenceManager refresh(), attach(), and connect() Methods" for more information.
See Chapter 3, "Using the Persistence Framework" for more information on entity managers.
Defining New Entity Attributes
When defining new entity attributes, look at the existing *-types.xsd files for examples of how to define various attributes. The XML tags you use to define new entity attributes are governed by the XMLSchema.xsd file. Be sure to include any referenced schemas in the package statement.
XSD is an industry standard. For information about writing XSD, see the W3C website:
http://www.w3.org/XML/Schema.html
To define attributes for a new entity, or to add new attributes to an existing entity:
-
Create a new XSD file.
The file name must end with -types.xsd. For example, myNewFile-types.xsd.
-
Open an existing *-types.xsd file.
-
Copy and paste an entity attribute definition from the existing file to your new file.
-
If defining attributes for a new entity, modify the copied entity attributes definition as needed:
-
Change the entity name to reflect the new entity name.
-
Change the attribute names to reflect the new attribute names.
-
Change the attribute types to reflect the new attribute types.
-
-
If adding new attributes to an existing entity, modify the copied entity attributes definition as needed:
-
Change the entity name to reflect the entity name that defines the attributes to which you are adding new attributes.
-
Change the attribute names to reflect the new attribute names you are adding.
-
Change the attribute types to reflect the new attribute types you are adding.
-
Defining New Enumerations
When defining new enumeration types, look at the existing *-enum-entities.xml files for examples of how to define them; when defining new enumeration values, look at the existing *-enum-types.xsd files for examples of how to define them. The XML tags you use to define new enumerations are governed by the XMLSchema.xsd file. Be sure to include any referenced schemas in the package statement.
Enumerations are an industry standard. For information about writing enumerations, see the W3C Web Services Enumeration website at:
http://www.w3.org/Submission/WS-Enumeration/
You can place all new enumeration types in one new file, and all new sets of enumeration values in another new file.
To define a new enumeration type:
-
Create a new XML file.
The file name must contain -enum- and end with -entities.xml. For example, myNew-enum-entities.xml.
-
Open an existing *-enum-entities.xml file.
-
Copy and paste an enumeration type definition from the existing file to your new file.
-
Modify the copied enumeration type definition as needed.
To define enumeration values for a new enumeration type, or to add new enumeration values to an existing enumeration type:
-
Create a new XSD file.
The file name must contain -enum- and end with -types.xsd. For example, myNewFile-types.xsd.
-
Open an existing *-enum-types.xsd file.
-
Copy and paste a set of enumeration values from the existing file to your new file.
-
If defining new enumeration values for a new enumeration type, modify the copied enumeration values as needed:
-
Change the enumeration type to reflect your new enumeration type.
-
Change the data type to reflect the data type of your new enumeration values.
-
Change the enumeration values to reflect your new enumeration values.
-
-
If adding new enumeration values to an existing enumeration type, modify the copied enumeration values as needed:
-
Change the enumeration type to reflect the name of the existing enumeration type to which you are adding the new enumeration values.
-
Change the data type to reflect the same data type as defined by the enumeration type to which you are adding the new enumeration values.
-
Change the enumeration values to reflect the new enumeration values you are adding to the enumeration type.
-
Defining New Native Sequences
When defining new native sequences, look at the existing ocim-entityidsequenceextension-entities.xml file for examples of how to define a native sequence and corresponding sequence generator name. Be sure to include any referenced schemas in the package statement.
To define a new native sequence, and specify an entity to use it:
-
Create a new XML file.
The file name must end with -entities.xml. The file name should also contain a meaningful reference so you can readily recognize the file content, such as -seqext-. For example, myNewSeqExts-entities.xml.
-
Open the existing ocim-entityidsequenceextension-entities.xml file.
-
Copy and paste a native sequence definition from the existing file to your new file.
-
Modify the copied native sequence definition as needed:
-
Change the name of the native sequence to reflect the name of your new native sequence.
-
Change the corresponding sequence generator name to reflect a functional name for your new native sequence.
-
-
Copy and paste an extended entity definition from the existing file to your new file.
-
Modify the copied extended entity definition as needed:
-
Change the entity name.
-
Change the specified sequence generator to your new sequence generator.
-
Extending Existing Entities
You can extend an existing entity using the XML tags defined in the package.xsd and *-plugin.xsd files that enable an entity's use of framework functionality. For example, you can extend an entity to be life-cycle enabled, capacity enabled, business-interaction enabled, place enabled, group enabled, and so forth. Each of these are functional areas of UIM that become available to an entity through the entity's original definition, or through an extension and custom code.
There are two kinds of existing entities: Explicitly-defined entities and capability-generated entities. For example, the Equipment entity is explicitly defined in the metadata, and includes the declaration of the consumable capability. As a result of this declaration, the EquipmentConsumer entity is generated, even though the EquipmentConsumer entity is not explicitly defined in the metadata.
Explicitly-defined entities and capability-generated entities are extended the same way, with one slight difference: When extending a capability-generated entity, you must include the extension tag.
Understanding the Extension Tag
The package.xsd file defines tags that are used to govern entity definitions. One such tag is the extension tag. Since entities are defined in *-entities.xml files, the extension tag may only be used within an *-entities.xml file.
You can use the extension tag to extend:
-
Capability-generated entities
-
Generated attributes of an explicitly-defined entity
-
Generated relationships of an explicitly-defined entity
For example, the following is an excerpt from the ocim-entityidsequenceextension-entities.xml file that extends the capability-generated EquipmentConsumer entity to use the ConsumerSeqGen native sequence:
<entity type="ocim:EquipmentConsumer"
entityIdSequenceGenerator="ConsumerSeqGen" extension="true"/>
A similar extension in the same file for the explicitly-defined Equipment entity does not require the extension tag because the entity is not capability-generated:
<entity type="ocim:Equipment"
entityIdSequenceGenerator="EquipmentSeqGen"/>
In another example, the TelephoneNumber entity is explicitly defined in the metadata, and by default has the Trackable Pattern as described in Oracle Communications Information Model Reference. The Trackable Pattern generates the createdDate, createdUser, lastModifiedDate, and lastModifiedUser attributes. You can extend any of these generated attributes through the use of the extension tag. For example, the following adds an index to the createdUser generated attribute:
<entity type="ocim:TelephoneNumber" extension="true">
<attribute name="createdUser" index="true"/>
</entity>
The TelephoneNumber entity explicitly defines several attributes, such as id, name, and description. So, a similar extension for an explicitly-defined attribute of TelephoneNumber does not require the extension tag because the attribute is not generated:
<entity type="ocim:TelephoneNumber"> <attribute name="id" index="true"/> </entity>
Note:
You cannot add the extension tag to the original entity definition; the tag must be placed in a separate entity definition that reflects the same name as the entity you are extending. The separate entity definition can reside in the same file as the original entity definition or in a separate file, but because Oracle recommends that you do not modify the metadata files directly, the separate entity definition should reside in a separate file.Note:
The extension tag that is defined by the package.xsd file should not be confused with the standard XSD extension tag, which is used to define entity attributes in the *-types.xsd files, or to define enumeration values in the *-enum-types.xsd files. For example, the ocim-equipment-types.xsd file defines the PipeRole entity to define the same attributes that the InventoryRole entity defines through the use of the standard XSD extension tag:
<xs:complexType name="PipeRole">
<xs:complexContent>
<xs:extension base="ocim:InventoryRole"/>
</xs:complexContent>
</xs:complexType>
Extending Existing Entities
You can extend an existing entity through a new *-entities.xml file that defines the same entity name and includes additional properties for the entity. When regenerating the entities:
-
For explicitly-defined entities, the properties defined for the entity in both files are merged together, resulting in the entity possessing the original properties and the extended properties.
-
For capability-generated entities, the properties of the generated entities and any extended definitions are merged together, resulting in the entity possessing the original generated properties and the extended properties.
To extend an existing entity:
-
Create a new XML file.
The file name must end with -entities.xml. For example, myNewFile-entities.xml.
-
Open an existing *-entities.xml file.
-
Copy and paste an entity definition from the existing file to your new file.
-
Modify the copied entity definition as needed:
-
The entity name must be the same name as the entity you are extending.
-
Add any tags to reflect the extension.
-
If you are extending a capability-generated entity, include the extension tag.
-
Extending Existing Entity Attributes
Extending an existing entity attribute is done in an *-entities.xml file, not in the *-types.xsd file.
You can extend an existing attribute using the XML tags defined for attributes in the package.xsd file. For example, you can extend an attribute definition to have an index, to be encrypted, or to have a maximum length that the database stores for an attribute. See "Understanding the Tags that Govern Definitions" for more information.
There are two kinds of existing attributes: Explicitly-defined attributes and capability-generated attributes. For example, the Equipment entity and its attributes are explicitly defined in the metadata. The Equipment entity definition includes the declaration of the life cycle management capability. As a result of this declaration, the adminState and objectState attributes are generated for the Equipment entity, even though they are not explicitly defined in the metadata.
Explicitly-defined attributes and capability-generated attributes are extended the same way, with one slight difference: When extending a capability-generated attribute, you must include the extension tag. See "Understanding the Extension Tag" for more information.
You can extend an existing attribute through a new *-entities.xml file that defines the same entity name, and includes the attribute extension. When regenerating the entities:
-
For explicitly-defined attributes, the properties defined for the attribute in both files are merged together, resulting in the attribute possessing the original properties and the extended properties.
-
For capability-generated attributes, the properties of the generated attributes and any extended definitions are merged together, resulting in the attribute possessing the original generated properties and the extended properties.
To extend an existing attribute:
-
Create a new XML file.
The file name must end with -entities.xml. For example, myNewFile-entities.xml.
-
Open an existing *-entities.xml file.
-
Copy and paste an entity definition from the existing file to your new file.
-
Modify the copied entity definition as needed:
-
The entity name must be the same name as the entity that defines or generates the attribute you are extending.
-
Update the tags to reflect the extension.
-
If you are extending a capability-generated entity, include the extension tag.
-
Extending Existing Enumerations
You cannot extend existing enumerations. To clarify, you can add new enumeration values to an existing set of enumeration values. See "Defining New Enumerations" for more information.
Extending Existing Native Sequences
You can extend the use of any UIM-defined native sequences to include additional entities.
To extend the use of UIM-defined native sequences:
-
Create a new XML file.
The file name must end with -entities.xml. The file name should also contain a meaningful reference so you can readily recognize the file content, such as -seqext-. For example, myNewSeqExts-entities.xml.
-
Open the existing ocim-entityidsequenceextension-entities.xml file.
-
Copy and paste an extended entity definition from the existing file to your new file.
-
Modify the copied extended entity definition as needed:
-
Change the entity name.
-
Change the specified sequence generator to a UIM-defined sequence generator that you want the entity to use.
-
If the entity is a capability-generated entity, include the extension tag.
-
You can also modify existing UIM-defined native sequences.
Note:
Oracle recommends that modifications to existing sequences be made before using UIM (before any sequence numbers have been generated).To modify existing UIM-defined native sequences:
-
Create a new XML file.
The file name must end with -entities.xml. The file name should also contain a meaningful reference so you can readily recognize the file content, such as -seqext-. For example, myNewSeqExts-entities.xml.
-
Open the existing ocim-entityidsequenceextension-entities.xml file.
-
Copy and paste an extended entity definition from the existing file to your new file.
-
In the copied file, modify the sequence definition as needed.
-
In the copied file, set the entityIdSequenceGeneratorPriority attribute to a value higher than the entityIdSequenceGeneratorPriority value in the original file so that the modified sequence overrides the original sequence.
-
If modifying the existing sequence after using UIM (after sequence numbers have been generated):
-
Determine which entities use the modified sequence.
-
For each entity using the sequence, determine the current maximum entityId value.
-
For each entity using the sequence, extend the entity definition to set the initialValue attribute to a value 50 to 100 higher than the current maximum entityId value.
See "Extending Existing Entities" and "Extending Existing Entity Attributes" for information on how to do this.
-
Applying Metadata Static Extensions
Statically extending the data model involves manually extending the metadata files. To apply the metadata static extensions:
-
Generate the entity source files from the metadata files
-
Compile the generated entity source files
-
Package the compiled entity source files in the inventory.ear, inventory-adapter.ear, and custom.ear files.
-
Deploy the inventory.ear, inventory-adapter.ear, and custom.ear files
You generate, compile, and package the entity source files using Ant targets that are provided in the ora_uim_entity_sdk_cartproj.zip/src/build.xml file.
About the build.xml File
The build.xml file defines several Ant targets that you can run to manage the database. An Ant target is a set of executable tasks that can be run using Ant. See "Running Ant Targets" for more information.
Note:
If you are running these Ant targets on Linux/Solaris, set the following variables:export COMPUTERNAME=hostName of Linux/Solaris machine export ANT_HOME=path to Ant installation
Table 4-1 describes the Ant targets defined in the build.xml file.
Table 4-1 build.xml Ant Targets
| Ant Target | Description |
|---|---|
|
entities |
From the metadata, this target generates entity source files and compiles them into entity Java classes. As a result, this target creates:
|
|
clean |
This target deletes the api/build and generated directories created by the entities Ant target. Oracle recommends that you always run the clean target prior to running the entities target. |
|
create.tables |
This target creates new database tables based on any new entities defined in the metadata; this target does not alter existing tables that were created as part of the UIM installation. To connect to the database in which you are creating tables, set the database credentials in step 8 of the procedure to generate, compile, and package the entity source files. See "Generating, Compiling, and Packaging the Entity Source Files" for more information. |
|
alter.tables |
This target creates new database tables based on any new entities defined in the metadata.This target also alters existing database tables based on any new attributes defined for existing entities in the metadata. To connect to the database in which you are creating or altering tables, set database credentials in step 8 of the procedure to generate, compile, and package the entity source files. See "Generating, Compiling, and Packaging the Entity Source Files" for more information. |
|
create.DDL |
This target creates the createDDL.jdbc and alterDDL.jdbc scripts based on any new entities defined in the metadata, or any new attributes defined for existing entities in the metadata. These files are placed in the ora_uim_entity_sdk/src/generated/entities/scripts directory. Run these scripts to create new database tables or alter existing database tables. The create.DDL target is used in place of the create.tables and alter.tables targets. |
|
update.earwithEntities |
This target updates the inventory-adapter.ear and uim_core_lib.ear files with the generated uim-entities.jar file. |
Generating, Compiling, and Packaging the Entity Source Files
To generate, compile, and package the entity source files for deployment:
-
Configure your Design Studio environment. Define the following system variables:
-
JAVA_HOME
See "Configuring Design Studio" for more information.
-
ANT_HOME
See "Configuring Ant" for more information.
-
-
In Design Studio, open the Studio Design perspective.
For instructions on how to open perspectives in Design Studio, see the Design Studio Help.
-
Import the UIM_Home/cartridges/tools/ora_uim_entity_sdk_cartproj.zip file.
For instructions on how to import a project into Design Studio using archive files, see the Design Studio Help.
-
Change to the Java perspective.
For instructions on how to change perspectives in Design Studio, see the Design Studio Help.
-
Copy and rename the ora_uim_entity_sdk/etc/COMPUTERNAME.properties file to HOSTNAME.properties, where HOSTNAME is the name of the computer where Design Studio is installed.
You can determine the computer name by running the following DOS command:
echo %COMPUTERNAME%
-
In the HOSTNAME.properties file, set the following properties to reflect your configuration:
-
UIM_HOME
-
DB_HOME
-
PROJECT_HOME
-
-
From a command line, navigate to your workspace ora_uim_entity_sdk/src directory, and run the following Ant command:
ant -f build_extract_poms_zip.xml
This command extracts the POMS SDK into the ora_uim_entity_sdk/src/platformFiles/extract directory.
-
In the ora_uim_entity_sdk/src/platformFiles/extract/objectmgmt/poms/config/poms.properties file, set the ConnectionUserName, ConnectionPassword, and ConnectionURL database credentials to reflect your database:
#Set datastore connection information for offline utilities. poms.ConnectionDriverName = oracle.jdbc.OracleDriver poms.ConnectionUserName = uimuser poms.ConnectionPassword = welcome@123 poms.ConnectionURL = jdbc:oracle:thin:@localhost:1521:XE
-
Configure the project library list.
For instructions on how configure the project library list, see the Design Studio Help.
Figure 4-1 shows the imported project library list, which includes the JAR files needed to compile the project.
Figure 4-1 Project Library List Before Configuring
Description of ''Figure 4-1 Project Library List Before Configuring''
Note:
The uim-entities.jar file gets created and placed in the specified directory by a later step in this procedure.The project library list of JAR files does not indicate the location of the files, so you must configure the project library list to point to the location of the JAR files. To do this, you need to add new variables named POMS_LIB and UIM_LIB that point the specified directory, as listed in Table 4-2.
Table 4-2 Location of JAR Files
Variable Name Directory Name POMS_LIB
Oracle_Home/POMSClient/lib
UIM_LIB
UIM_Home/lib
Figure 4-2 shows the project library list after the variables are added. Notice that the library list now includes the location of the JAR files, not just the JAR file names.
Figure 4-2 Project Library List After Configuring
Description of ''Figure 4-2 Project Library List After Configuring''
-
Add any new metadata files to the ora_uim_src_entity/src/api directory. See "Extending the Data Model Through the Metadata Files" for more information.
-
Modify the ora_uim_src_entity/src/api/custom-model-lib.xml file to include any new metadata files in the build. For example, if you have created new files named my-entities.xml and my-entities.xsd, you need to add these file names in the custom-model-lib.xml as follows:
-
Add any custom Java code that supports new entities to the ora_uim_src_entity/src/api/src-man directory. For example, defining new entities in the metadata requires creating new entity managers. See "Creating New Entity Managers" for more information.
-
From a command line, navigate to your workspace ora_uim_src_entity/src directory, and run the following Ant command:
ant entities
This command creates the uim-entities.jar file and places it in the ora_uim_src_entity/src/generated/inventory/APP_INF/lib directory. The uim-entities.jar file contains the entity Java classes for all UIM entities and all custom entities. See "About the build.xml File" for more information.
-
Make a backup copy of the following files:
-
UIM_Home/app/inventory-adapter.ear
-
UIM_Home/app/7_2_x/uim_core_lib.ear
-
-
From a command line, navigate to your workspace ora_uim_src_entity/src directory and run the following Ant command:
ant update.earwithEntities
This command updates the inventory-adapter.ear and uim_core_lib.ear files with the uim_entities.jar file created in step 13. See "About the build.xml File" for more information.
-
If your Domain_Home/servers/serverName/upload/oracle.communications. inventory.corelib/7_2_x/app directory contains a uim_core_lib.ear file:
-
Make a backup copy of this uim_core_lib.ear file.
-
Copy Domain_Home/UIM/app/7_2_x/uim_core_lib.ear to Domain_Home/ servers/serverName/upload/oracle.communications.inventory.corelib/7_2_x/app.
-
-
From a command line, navigate to your workspace ora_uim_src_entity/src directory and run one of the following set of Ant commands:
ant create.tables ant alter.tables
or
ant create.DDL
These commands update the database either directly (create.tables, alter.tables), or indirectly through a script (create.DDL). See "About the build.xml File" for more information.
-
Deploy the updated inventory-adapter.ear file.
-
Deploy the updated uim_core_lib.ear file.
-
If you have custom Java code in the ora_uim_entity_sdk project, deploy the resultant ora_uim_entity_sdk.jar file (cartridge) from the Studio environment into UIM.
Deploying the cartridge adds your custom Java code to the UIM_Home/app/7_2_x/uim_custom_lib.ear file.
-
Deploy the inventory.ear file. At the time of deploying this EAR file, you must name this application oracle.communications.inventory.
-
If you added custom code, deploy the custom.ear file.
More on Entity Definitions
This section further describes entity definitions, focusing on:
Understanding Entity Capability Definitions
A capability is a design pattern that is applied to an entity, such as enabling an entity to be life-cycle managed. A capability is declared in the metadata using tags, and results in the generation of attributes and related entities that are not explicitly defined in the *-entities.xml or *-types.xsd files.
For example, an entity that is life-cycle-managed progresses through a succession of states during the course of its life. For life-cycle-managed entities, UIM tracks two states: administrative state and object state. To support this capability, an entity must define the adminState and objectState attributes. Rather than declare these attributes in the *-types.xsd of every entity that supports this pattern, the capability is declared for the entity in the *-entities.xml file using the <lifeCycle> element stateType tag. As a result of this tag, the adminState and objectState attributes are generated on the entity, and the corresponding columns are generated on the database table.
The package.xsd and *-plugin.xsd files defines the tags that are available to declare a capability. Some capability definitions are modularized, such as the capacity, characteristic, consumable, and group-enabled capabilities, as defined in the following *-plugin.xsd files:
-
capacity-plugin.xsd
-
characteristic-plugin.xsd
-
consumable-plugin.xsd
-
groupenabled-plugin.xsd
Other *-plugin.xsd files include:
-
core-plugin.xsd
-
uim-plugin.xsd
The design patterns that are declared as capabilities are documented in Oracle Communications Information Model Reference.
Understanding Entity Relationship and Collection Definitions
Note:
For information on all possible elements and attributes that can be used to define entity relationships and collections, see the package.xsd file.The *.entities.xml files define entities and their relationships to other entities. Relationships between entities can be categorized into two types: Uni-directional and bi-directional. A uni-directional relationship only allows one-way traversal from one entity to another; a bi-directional relationship allows traversal both ways. The relationships can also be separated into three cardinalities: One-to-one, one-to-many, and many-to-many. Types and cardinalities of relationships result in any given entity relationship falling into one of six different combinations. Examples of these six different combinations are described in the following sections.
The direction of the relationships is not the determining factor of how primary and foreign keys are defined in the physical model. It affects only how the logical object model is defined. However, the relationship cardinality and ownership dictates the primary-foreign keys and join table definitions.
Relational and collection-type attributes can also be dependent. The entity or collection of entities referenced by a dependent attribute is deleted when the owning entity is deleted.
Uni-Directional, One-to-One Relationship
In Example 4-11, TopologyProfileEdge has a reference to TopologyEdge, but TopologyEdge does not have a reference to TopologyProfileEdge.
Example 4-11 Uni-Directional, One-to-One Relationship
<entity type="ocim:TopologyProfileEdge" interface="oracle.communications.inventory.api.entity.TopologyProfileEdge" accessControlled="true" entityIdSequenceGenerator="TopologySeqGen">
.
.
.
<!-- One-Sided One-to-One TopologyProfileEdge to TopologyEdge -->
<relationship name="topologyEdge">
<otherSide type="ocim:TopologyEdge"/>
<javadoc>
The TopologyEdge that contains the TopologyProfileEdge.
</javadoc>
</relationship>
</entity>
Uni-Directional, One-to-Many Relationship
In Example 4-12, CharactersticSpecification has a reference to a collection of CharacteristicSpecValue entities, but a CharacteristicSpecValue does not have a reference back to the CharacteristicSpecification. The relationship can be omitted only on the many side. The CharacteristicSpecification ENTITYID foreign key is still realized physically as a column in the CharacteristicSpecValue table. However, a CharacteristicSpecValue entity does not have a Java attribute generated that allows the traversal back to the CharacteristicSpecification.
Example 4-12 Uni-Directional, One-to-Many Relationship
<entity type="ocim:CharacteristicSpecification" interface="oracle.communications.inventory.api.entity.CharacteristicSpecification" timeBound="true">
<implements interface="java.lang.Cloneable"/>
.
.
.
<!-- One-Sided One-to-Many
CharacteristicSpecification to CharacteristicSpecValue-->
<relationship name="values">
<thisSide collection="java.util.HashSet"/>
<otherSide dependent="true" type="ocim:CharacteristicSpecValue"/>
</relationship>
</entity>
The collection data type is defined as a java.util.ArrayList. EclipseLink suggests that java.util.HashSet be used whenever possible to achieve better performance on their smart proxies logic because list-type collections such as ArrayList require sequential ordering for the elements for indexed access and allow for duplicate values of elements. Therefore, if the usage pattern of the collection attributes does not involve direct indexed access to a specific element, and the elements are unique within the collection, set-type collections should be used instead.
Uni-Directional, Many-to-Many Relationship
There is no example in UIM of a uni-directional, many-to-many relationship; however, it is a valid relationship. Using a scenario of entity1 and entity2, entity1 is applicable to multiple entity2s, and each entity2 has access to multiple entity1s. However, only entity1 has a collection of entity2s. A join table is required for the many-to-many relationship.
In this relationship, the logical object model does not provide immediate insight that the relationship is many-to-many. From the entity1 point of view, it is one-entity1-to-many-entity2s. The logical object model does not show the many-to-many cardinality because there is no relationship back to entity1. However, the physical model exhibits the many-to-many relationship through the use of the join table.
Bi-Directional, One-to-One Relationship
In Example 4-13, Equipment has a reference to EquipmentEquipmentRel, and EquipmentEquipmentRel has a reference back to its sole Equipment. The relationship is owned by the Equipment and the EquipmentEquipmentRel is dependent on the Equipment.
The relationship name is used for generating the attribute name in the entity.
Example 4-13 Bi-Directional, One-to-One Relationship
<entity type="ocim:Equipment" interface="oracle.communications.inventory.api.entity.Equipment" accessControlled="true" entityIdSequenceGenerator="EquipmentSeqGen">
.
.
.
<!-- Two-Sided One-to-One Equipment to EquipmentEquipmentRel (B) -->
<relationship name="parentEquipment">
<thisSide inverse="true"/>
<otherSide type="ocim:EquipmentEquipmentRel"
attribute="childEquipment"/>
<javadoc>
The holding parent equipment.
</javadoc>
</relationship>
</entity>
.
.
.
<entity type="ocim:EquipmentEquipmentRel" interface="oracle.communications.inventory.api.entity.EquipmentEquipmentRel" table="Eq_EqRel" accessControlled="true" entityIdSequenceGenerator="EquipmentSeqGen">
.
.
.
<!-- Two-Sided One-to-One EquipmentEquipmentRel to Equipment -->
<relationship name="childEquipment">
<otherSide type="ocim:Equipment" attribute="parentEquipment"/>
</relationship>
</entity>
Bi-Directional, One-to-Many Relationship
In Example 4-14, Equipment has a reference to a collection of EquipmentHolderEquipmentRel entities, and EquipmentHolderEquipmentRel has a reference back to Equipment.
The inverse relationship is always on the one side of the relationship because the foreign key is on the many side. The relationship is owned by the Equipment. The collection of EquipmentHolderEquipmentRel entities is defined as dependent. As a dependent collection, the entities in the collection are deleted automatically when the owner entity is deleted. A dependent property is also applicable to simple no-collection type attributes.
Example 4-14 Bi-Directional, One-to-Many Relationship
<entity type="ocim:Equipment" interface="oracle.communications.inventory.api.entity.Equipment" accessControlled="true" entityIdSequenceGenerator="EquipmentSeqGen">
.
.
.
<!-- Two-Sided One-to-Many Equipment to EquipmentEquipmentHolderRel -->
<relationship name="parentEquipmentHolders">
<thisSide inverse="true" collection="java.util.HashSet"/>
<otherSide dependent="true" type="ocim:EquipmentHolderEquipmentRel"
attribute="equipment"/>
<javadoc>
Set of parent equipment holders the equipment is held by.
</javadoc>
</relationship>
</entity>
.
.
.
<entity type="ocim:EquipmentHolderEquipmentRel" interface="oracle.communications.inventory.api.entity.EquipmentHolderEquipmentRel" table="EqHolder_EqRel" accessControlled="true" entityIdSequenceGenerator="EquipmentSeqGen">
.
.
.
<!-- Two-Sided Many-to-One EquipmentHolderEquipmentRel to Equipment -->
<relationship name="equipment">
<otherSide type="ocim:Equipment" attribute="parentEquipmentHolders"/>
<javadoc>
The child equipment.
</javadoc>
</relationship>
</entity>
Bi-Directional, Many-to-Many Relationship
In Example 4-15, Equipment can have multiple DeviceInterface entities, and each DeviceInterface entity can be applicable to many Equipment entities. A value of inverse="true" means that the other side of a two-way relationship owns the foreign key. In a many-to-many relationship, the inverse is arbitrary because there should be a join table created. In this case, the inverse="true" defines the other side as the owner of the relationship. Collection types include ArrayList and HashMap. See the EclipseLink documentation for all supported collection types.
Example 4-15 Bi-Directional, Many-To-Many Relationship
<entity type="ocim:Equipment" interface="oracle.communications.inventory.api.entity.Equipment" accessControlled="true" entityIdSequenceGenerator="EquipmentSeqGen">
.
.
.
<!-- Two-Sided Many-to-Many Equipment to DeviceInterface-->
<relationship name="supportedDeviceInterfaces">
<join table="equipment_deviceinterface"/>
<thisSide inverse="true" collection="java.util.HashSet"/>
<otherSide type="ocim:DeviceInterface"/>
<javadoc>
The list of mapped device interaces supported by the equipment.
</javadoc>
</relationship>
</entity>
.
.
.
<entity type="ocim:DeviceInterface" interface="oracle.communications.inventory.api.entity.DeviceInterface" accessControlled="true" entityIdSequenceGenerator="LogicalDeviceSeqGen">
.
.
.
<!-- Two-Sided Many-to-Many DeviceInterface to Equipment-->
<relationship name="supportingEquipment">
<join table="equipment_deviceinterface"/>
<thisSide collection="java.util.HashSet"/>
<otherSide type="ocim:Equipment"/>
<javadoc>
The list of equipment up the hierarchy that supports the device
interface mapping. This will only be populated if the device
interface is mapped.
</javadoc>
</relationship>
</entity>
Relationship Definition Affect on Generated Entities
Each relationship definition adds an attribute to the generated entity for which it is defined. For a uni-directional relationship, an attribute is generated for the owning entity. For a bi-directional relationship, an attribute is generated for the owning entity and for the dependent entity.
Example 4-16 is an excerpt from the uim-rule-entities.xml file that defines the extensionPoint, ruleSetEntity, and specification relationships for the ExtensionPointRuleSet entity.
Example 4-16 Entity Definition
<entity type="ocim:ExtensionPointRuleSet" interface="oracle.communications.inventory.api.entity.ExtensionPointRuleSet">
<identifier>
<attribute>extensionPoint</attribute>
<attribute>ruleSetEntity</attribute>
<attribute>specification</attribute>
</identifier>
<!-- Two-Sided Many-to-One ExtensionPointRuleSet to ExtensionPoint -->
<relationship name="extensionPoint">
<otherSide type="ocim:ExtensionPoint" attribute="extensionPointRuleSets"/>
</relationship>
<!-- Two-Sided Many-to-One ExtensionPointRuleSet to RuleSetEntity -->
<relationship name="ruleSetEntity">
<otherSide type="ocim:RuleSetEntity" attribute="extensionPointRuleSets"/>
</relationship>
<!-- Two-Sided Many-to-One ExtensionPointRuleSet to Specification -->
<relationship name="specification">
<otherSide type="ocim:Specification"
attribute="extensionPointRuleSets"/>
</relationship>
</entity>
Example 4-17 is an excerpt from the uim-rule-types.xsd file that defines the type attribute and the sequence attribute for the ExtensionPointRuleSet entity.
Example 4-17 Entity Attributes Definition
<xs:complexType name="ExtensionPointRuleSet">
<xs:annotation>
<xs:documentation>
Associates extension points and rulesets.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="type" type="ocim:ExtensionPointRuleSetType">
</xs:annotation>
</xs:element>
<xs:element name="sequence" type="integer">
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
Example 4-18 is a code excerpt from the ExtensionPointRuleSet generated source file that defines the attributes for ExtensionPointRuleSet entity. The type attribute and the sequence attribute are generated based on the attributes defined in the uim-rule-types.xsd file for the ExtensionPointRuleSet entity. The fields extensionPoint, ruleSetEntity, and specification are generated based on the relationships defined in the uim-rule-entities.xml file for the ExtensionPointRuleSet entity.
Example 4-18 Generated Source File
/*
* ExtensionPointRuleSet.java
* [CODE-GENERATED]
*/
package oracle.communications.inventory.api.entity;
/**
* Associates extension points and rulesets.
*/
public interface ExtensionPointRuleSet
extends java.io.Serializable,
oracle.communications.platform.persistence.Persistent,
oracle.communications.inventory.api.Trackable
{
public static final
oracle.communications.platform.persistence.impl.EntityField _type = new oracle.communications.platform.persistence.impl.EntityField(ExtensionPointRuleSet.class, "type");
public static final
oracle.communications.platform.persistence.impl.EntityField _sequence = new oracle.communications.platform.persistence.impl.EntityField(ExtensionPointRuleSet.class, "sequence");
public static final
oracle.communications.platform.persistence.impl.EntityField _extensionPoint = new oracle.communications.platform.persistence.impl.EntityField(ExtensionPointRuleSet.class, "extensionPoint");
public static final
oracle.communications.platform.persistence.impl.EntityField _ruleSetEntity = new oracle.communications.platform.persistence.impl.EntityField(ExtensionPointRuleSet.class, "ruleSetEntity");
public static final
oracle.communications.platform.persistence.impl.EntityField _specification = new oracle.communications.platform.persistence.impl.EntityField(ExtensionPointRuleSet.class, "specification");
Taking the example one step further, you can look at the generated source code for the ExtensionPoint, RuleSetEntity, and Specification entities. These entities are defined as the other side of the bi-directional relationships in Example 4-16, "Entity Definition". All three generated source files define the extensionPointRuleSets attribute, as defined by the otherSide attribute for each.
Understanding Entity Manager Definitions
The persistence framework manages the database and the mapping between the database and the entity classes. An entity manager manages the database tables for a specific functional area. For example, EquipmentManager manages the Equipment table, but it also manages EquipmentHolder, PhysicalPort, PhysicalConnector, PhysicalDevice, and so forth.
Defining Entity Managers
Entity managers are UIM classes. As a result, entity managers are defined in uim-*-entities.xml files, and not in ocim-*-entities.xml files. Entity managers are defined using the <manager> element and interface attribute that are defined in the package.xsd file. Example 4-19 is an excerpt from the uim-equipment-entities.xml file that shows the EquipmentManager entity manager definition.
Example 4-19 Entity Manager Definition
<manager interface="oracle.communications.inventory.api.equipment.EquipmentManager" class="oracle.communications.inventory.api.equipment.impl.EquipmentManagerImpl"/>
Upon installation of UIM, every entity manager that is defined in the metadata has a corresponding entity manager and implementation of the manager. For example, based on the excerpt shown in Example 4-19, the following classes exist:
-
EquipmentManager
-
EquipmentManagerImpl
If you extend the data model by creating a new entity, you must also create a new entity manager, and implementation of the manager, to manage the entity data. See "Creating New Entity Managers" for more information.
The relationship of entity to entity manager is not one-to-one. For example, ocim-equipment-entities.xml defines several entities, each of which defines its own entity interface. An entity interface differs from a manager interface; an entity interface defines the getter and setter methods for entity attributes, while a manager interface defines methods for the entity, such as the createEquipment(), getEquipment(), or updateEquipment() methods. Example 4-20 is an excerpt from the ocim-equipment-entities.xml file that shows a portion of the Equipment and EquipmentHolder entity definitions.
Example 4-20 Entity Definition
<entity type="ocim:Equipment"
interface="oracle.communications.inventory.api.entity.Equipment"
accessControlled="true" entityIdSequenceGenerator="EquipmentSeqGen">
<entity type="ocim:EquipmentHolder"
interface="oracle.communications.inventory.api.entity.EquipmentHolder"
accessControlled="true" entityIdSequenceGenerator="EquipmentSeqGen">
Both of these entities are extended in the uim-equipment-entities.xml file, as shown in Example 4-21.
Example 4-21 ManagedBy Declarations
<entity type="ocim:Equipment"
managedBy="oracle.communications.inventory.api.equipment.EquipmentManager">
<entity type="ocim:EquipmentHolder"
managedBy="oracle.communications.inventory.api.equipment.EquipmentManager">
The managedBy tag is only present on entities that are business-interaction enabled. For business-interaction enabled entities, the managedBy tag specifies which entity manager manages the entity.