5 Working with the POMS SDK

One-to-one Relationships

When a relationship refers to a single entity, the entity is accessed directly. For example, the mapped physical and logical devices:

public oracle.communications.inventory.api.entity.LogicalDevice getMappedLogicalDevice();
public void setMappedLogicalDevice( oracle.communications.inventory.api.entity.LogicalDevice mappedLogicalDevice );

One-to-Many or Many-to-Many Relationships

When a relationship refers to multiple entities, the entities are accessed through a collection. For example, the equipment to physical port relationship:

public java.util.List<oracle.communications.inventory.api.entity.PhysicalPort> getPhysicalPorts();
public void setPhysicalPorts( java.util.List<oracle.communications.inventory.api.entity.PhysicalPort> physicalPorts );

A getter never returns null for the collection. If there are no related entities, an empty collection is returned. That means the developer can safely add entities without creating a collection. For example:

equipment.getPhysicalPorts().add(physicalPort);

Ordered and Unordered Relationships

POMS uses a List for the collection because the Oracle Communications Information Model defines an ordered relationship for physical ports on equipment. In other cases, order does not matter and so POMS uses a Set for the collection. For example, the parent relationship from Equipment to EquipmentHolder:

public java.util.Set<oracle.communications.inventory.api.entity.EquipmentHolderEquipmentRel> getParentEquipmentHolders();
public void setParentEquipmentHolders(java.util.Set<oracle.communications.inventory.api.entity.EquipmentHolderEquipmentRel> equipmentHolders);

Bi-directional Relationships

Certain relationships in the model are bi-directional. POMS includes accessors on entities on both sides of a bi-directional relationship, and the relationship can be set from either side. The physical device to logical device relationship described in the "One-to-one Relationships" example is bi-directional. The other side of this relationship, on the logical device, is defined as:

public java.util.List<oracle.communications.inventory.api.entity.PhysicalDevice> getMappedPhysicalDevices();
public void setMappedPhysicalDevices( java.util.List<oracle.communications.inventory.api.entity.PhysicalDevice> mappedPhysicalDevices );

This is a many-to-one relationship, so there is a collection on the logical device side and single entity on the physical device side. To relate a physical and logical device, you can either set from the physical device:

physicalDevice.setMappedLogicalDevice(logicalDevice);

or set from the logical device:

logicalDevice.getMappedPhysicalDevices ().add(physicalDevice);

Relationship Entities

In some cases, the model defines an intermediate relationship entity instead of relating two entities directly. For example, the Information Model defines EquipmentEquipmentRel to relate two pieces of equipment. To create this type of relationship, instantiate the relationship entity and set the related entities. For the equipment to equipment example:

EquipmentEquipmentRel parentEquipmentRel = PersistenceHelper.makeEntity(EquipmentEquipmentRel.class);
parentEquipmentRel.setChildEquipment(equipment);
parentEquipmentRel.setParentEquipment(parentEquipment);

Find by Entity

To find entities matching an example entity, instantiate an entity of the appropriate type and set one or more attributes. Use the findByEntity method to return a collection of matching entities. Here is an example that looks for the specification for a Cisco 3640 physical device:

Finder finder = PersistenceHelper.makeFinder();
PhysicalDeviceSpecification example = 
    PersistenceHelper.makeEntity(PhysicalDeviceSpecification.class);
example.setName("Cisco3640");

Collection<PhysicalDeviceSpecification> specifications = 
    finder.findByEntity(example, "name");
if (specifications.size() == 1) {
    System.out.println("found specification");
}

Find by JPQL

Java Persistence Query Language (JPQL) is a powerful way to express queries. The following examples can be understood without knowing JPQL, especially if the developer is familiar with SQL; however, you must learn JPQL to build their own queries.

For an introduction to JPQL, use the following link:

https://download.oracle.com/javaee/6/tutorial/doc/bnbtg.html.

To perform a JPQL query use the following workflow:

1. Instantiate a Finder.

2. Initialize any parameters (these parameters are bound to variables in the JPQL expression).

3. Specify the desired result type.

4. Use the findByJPQL method to return matching results.

In following example queries, the first is equivalent to the example in the "Find by Entity" section and returns a particular specification. The second uses a join in the JPQL expression to return all physical devices that use this specification.

Finder finder = PersistenceHelper.makeFinder();
finder.addParameter("name", "Cisco3640");
finder.setRsultClass(PhysicalDeviceSpecification.class);
Collection< PhysicalDeviceSpecification> specifications = finder.findByJPQL(
                 "SELECT o FROM PhysicalDeviceSpecification o " + 
                 "WHERE o.name = :name");
 
finder.setRsultClass(PhysicalDevice.class);
Collection< PhysicalDevice> cisco3640Devices = finder.findByJPQL(
                 "SELECT o FROM PhysicalDevice o JOIN o.specification s " +
                 "WHERE s.name = :name");

A JPQL query does not need to return complete entities. It can return one or more attributes from matched entities. To return only name and ID from a physical device, the developer would modify the previous example as follows:

Collection cisco3640Devices = finder.findByJPQL(
                 "SELECT o.name,o.id FROM PhysicalDevice o JOIN o.specification s WHERE s.name = :name");
for (Oject device : cisco3640Devices) {
    Object[] attributes = (cisco3640DevicesObject[]) device;
    System.out.println("Found Cisco 3640 named " + attributes[0] + " with id " + 
    attributes[1]);
} 

The code snippet also shows how to iterate over the results. Since the returned type is not a POMS entity, the attribute values are available as Object arrays. You would not set the result class in this case.

While JPQL and the Finder support operations that modify persisted data (update, delete, and so on), you should never modify POMS data with JPQL. The Finder is intended only for read operations.

Find with Paged Results

When working with a large number of entities, process them in smaller batches to reduce memory usage. The Finder supports paged results. Initialize the Finder normally, then specify the range of value to retrieve. This modifies the original physical device example to page through devices 20 at a time:

int pageSize = 20;
int start = 0;
while (true) {
   finder.setRange(start, start + pageSize - 1);
   Collection<Physicaldevice> cisco3640Devices = finder.findByJPQL(
       "SELECT o FROM PhysicalDevice o JOIN o.specification s WHERE s.name = :name");
    for (PhysicalDevice device : cisco3640Devices) {
        System.out.println(device.getName());
        if (cisco3640Devices.size()) < pageSize) {
            break;
        }
        start += pageSize;
    }
}

POMS SDK Interfaces

The following are the PersistenceHelper API methods:

public static < E extends Object > E makeEntity( Class< E > entity );
public static oracle.communications.platform.persistence.Finder makeFinder( ) ;

The following are the Finder API methods:

/**
     * Set the result Class to query.
     * 
     * @param resultClass
     *            the interface of each result in the result set
     */
    public void setResultClass(Class resultClass);
 
/**
     * Set the range of the result set to return, starting of the zero-based
     * start index and ending at the end index, exclusive. For example,
     * setRange(0,5) returns 5 results indexed at 0 thru 4.
     * 
     * <p>
     * Setting the range is meaningless if the order of the results is not
     * consistent. setOrdering is assumed.
     * 
     * @param start
     *            zero-based start index
     * @param end
     *            ending index, exclusive
     * @see javax.jdo.Query#setRange
     */
    public void setRange(long start, long end);
 
    /**
     * Add the parameter name and value that are used to define the filter.
     * 
     * <p>
     * Parameter names beginning with an underscore ('_') are illegal. They may
     * conflict with additional parameters used internally by this Finder.
     * 
     * @param names
     *            the parameter name to be declared
     * @param param
     *            the parameter value to be bound to the query
     * @throws java.lang.IllegalArgumentException
     *             if illegal parameters are passed
     */
    public void addParameter(String name, Object param);
/**
     * Find entities by example.
     * Any non-null attributes in the example entity is used as the search criteria, however
     * the attribute names in the mustUseAttributes argument are used as criteria if the
     * attribute is null.
     * 
     * <p>
     * This is a convenience method that performs a simple query in one call.
     * Incremental query construction is not over-written by calling this
     * method.
     * 
     * @param entity
     *            the example entity which non-null attributes are used as the search criteria.
     * @param attributes
     *            list of attribute names which must be used as search criteria even if their values
     *            in the example entity are null.
     * @param <E>
     *            a oracle.communications.platform.persistence.Persistent type
     * @return Collection of results of the matching entities
     */
    public < E extends Persistent > Collection< E > findByEntity( E entity, String ... mustUseAttributes );
/**
     * This method returns the result of executing a JPQL search using the passed expression.
     * The caller can pass the query parameter with {@link #addParameter(Integer, Object) addParameter} or
     * {@link #addParameter(String, Object) addParameter}.
     * 
     * @param jpql The JPQL
     * @return Collection of search results
     */
    public Collection findByJPQL(String jpql);