oracle.forms.jdapi
Interface JdapiObject

All Known Implementing Classes:
oracle.forms.jdapi.BaseFormsObject

public interface JdapiObject

This interface represents the supertype and common behaviours for all Forms objects, and can be used to build and modify Forms applications generically, that is, without referring to the specific object types.

All Jdapi Forms object classes implement the JdapiObject interface, which is also the fundamental type of all objects. As a result, they have access to these useful methods:

Each real object type is identified by a single unique constant. This constant is returned by the getTypeId. Many of the methods in this class take a property type ID constant as a parameter (propertyTypeId). These constants represent specific Forms object properties.


Field Summary
static int PROPERTY_DEFAULT_VALUE
          Constant for default property state
static int PROPERTY_INHERITED_VALUE
          Constant for inherited property state
static int PROPERTY_OVERRIDDEN_DEFAULT_VALUE
          Constant for overridden default property state
static int PROPERTY_OVERRIDDEN_INHERITED_VALUE
          Constant for overridden inherited property state
static int PROPERTY_STATE_UNKNOWN
          Constant for unknown property state
 
Method Summary
 void changeOwner(JdapiObject newOwner)
          Assigns a new owner to the referred object.
 JdapiObject clone(JdapiObject parent, java.lang.String newName)
          Creates a clone of the specified object, creating a new object with the given name and owner.
 JdapiObject createSubclassedChild(JdapiObject childOwner, java.lang.String childName)
          Subclass the referred object.
 void destroy()
          Destroys the specified Forms object and all the other objects it owns.
 boolean equals(JdapiObject object)
          Compares two objects and determines if they are equal.
 boolean getBooleanProperty(int propertyTypeId)
          Retrieves a boolean property from the referred object.
 JdapiIterator getChildObjectProperty(int propertyTypeId)
          Retrieves child objects for a given property value.
 java.lang.String getClassName()
          Returns the class name of the object.
 java.lang.Object getClientInfo()
          Returns the client info object associated with this Object.
 int getIntegerProperty(int propertyTypeId)
          Retrieves an integer property from the referred object.
 java.lang.String getIntegerPropertyString(int propertyTypeId)
          Gets a numeric (long) property value's text representation.
 JdapiMetaObject getJdapiMetaObject()
          Gets the metadata object for the specified object.
 JdapiIterator getMetaProperties()
          Return an iterator over the meta properties in object referred.
 JdapiObject getModule()
          Returns the module object that the current object refers to.
 java.lang.String getName()
          Returns the name of this object.
 JdapiObject getObjectProperty(int propertyTypeId)
          Retrieves a JdapiObject property from the referred object.
 JdapiIterator getOwnedObjects()
          Returns an iterator over the list of objects that the referred object owns.
 JdapiObject getOwner()
          Returns the owner of the referred object.
 Blob getPersistentClientInfoBlob()
          Returns the persistent client info Blob associated with this object.
 java.lang.Object getPersistentClientInfoObject()
          Returns the persistent client info Java object associated with this object.
 int getPropertyState(int propertyTypeId)
           A property can be in one of the 4 states.
DEFAULT_VALUE : has its default value
DEFAULT_VALUE_OVERRIDEN : locally overrides its default value
INHERITED_VALUE : inherits its ancestor's value
INHERITED_VALUE_OVERRIDDEN : locally overrides its ancestor's value
 java.lang.String getPropertyValueName(int propertyTypeId, int val)
          Gets the string representation of a given property's value.
 java.lang.String getQualifiedName(boolean includeModule)
          Determines whether the fully-qualified name of the object is returned.
 int getStringIDProperty(int propertyTypeId)
          Retrieves a special String ID (integer) property from the referred object.
 java.lang.String getStringProperty(int propertyTypeId)
          Retrieves a string property from the referred object.
 JdapiObject getSubclassParent()
          Returns the subclassing parent of the specified object.
 int getTypeId()
          Returns the integer Forms object type that represents this object.
 boolean hasDefaultedProperty(int propertyTypeId)
          Checks if a property is set to it's default value.
 boolean hasInheritedProperty(int propertyTypeId)
          Checks if a property is inherited.
 boolean hasOverriddenProperty(int propertyTypeId)
          Determine whether the object referred has a property of the given type id with an overridden value.
 boolean hasProperty(int propertyTypeId)
          Determines if the referred object has the specified property.
 void inheritProperty(int propertyTypeId)
          Resets a property to it's default value (confusing name eh?).
 boolean isSubclassed()
          Determines whether the specified object has a subclassing parent.
 boolean isValidFormsObject()
          Determines whether this Java instance references a valid Forms object.
 void move(JdapiObject nextObject)
          Reorders an object with respect to its siblings in the collection it belongs to.
 int queryType()
          Returns the FormAPI object type ID (x_OTID in JdapiTypes).
 void reattach()
          Reattaches subclassed object.
 void setBooleanProperty(int propertyTypeId, boolean propertyValue)
          Sets the value of the specified boolean property belonging to the referred object.
 void setClientInfo(java.lang.Object clientInfo)
          Sets the client information.
 void setIntegerProperty(int propertyTypeId, int propertyValue)
          Sets the value of the specified integer property belonging to the referred object.
 void setObjectProperty(int propertyTypeId, JdapiObject propertyValue)
          Sets the value of the specified object property value for the object.
 void setPersistentClientInfo(Blob val)
          Sets persistent client info for this object.
 void setPersistentClientInfo(java.io.Serializable val)
          Serializes any Java object which supports the Serializable interface to this object's Persistent Client Info.
 void setStringProperty(int propertyTypeId, java.lang.String propertyValue)
          Sets the value of the specified string property for the object.
 void setSubclassParent(JdapiObject parent)
          Change the subclassing parent of the object referred.
 java.lang.String toString()
          Converts and returns the object properties to string format.
 

Field Detail

PROPERTY_STATE_UNKNOWN

public static final int PROPERTY_STATE_UNKNOWN
Constant for unknown property state

PROPERTY_DEFAULT_VALUE

public static final int PROPERTY_DEFAULT_VALUE
Constant for default property state

PROPERTY_OVERRIDDEN_DEFAULT_VALUE

public static final int PROPERTY_OVERRIDDEN_DEFAULT_VALUE
Constant for overridden default property state

PROPERTY_INHERITED_VALUE

public static final int PROPERTY_INHERITED_VALUE
Constant for inherited property state

PROPERTY_OVERRIDDEN_INHERITED_VALUE

public static final int PROPERTY_OVERRIDDEN_INHERITED_VALUE
Constant for overridden inherited property state
Method Detail

destroy

public void destroy()
Destroys the specified Forms object and all the other objects it owns. The object and any children it might posess are removed from memory, detached from its owner object and cease to exist. For example, there is no need to explicitly iterate through a module hierarchy destroying all its owned objects before destroying the module. Any references to the object are also removed.

The following code sample creates a Forms module containing a block and items, then destroys the entire module by a single call to destroy().

      // create a module from scratch 
      FormModule fmd = new FormModule("MODULE_ONE");
      Block blockA = new Block(fmd, "EMP");
      Item itemA = new Item(blockA, "ID");
      Item itemB = new Item(blockA, "NAME");
      Item itemC = new Item(blockA, "LOCATION");
      fmd.save("D:/work/Module_One.fmb");
      fmd.destroy();
 

clone

public JdapiObject clone(JdapiObject parent,
                         java.lang.String newName)
Creates a clone of the specified object, creating a new object with the given name and owner. For example, given a Block in Form A, you can clone it into Form B by passing Form B in the parent parameter, and specifying a new name for the block in the newName parameter.

The new object is the same as the original object in that it has the same property values. However, subclassing information is discarded, and the inherited property values "flattened" into local values in the new object.

Parameters:
parent - owner of the new object.
newName - name of the new object.
Returns:
the clone of the object.

move

public void move(JdapiObject nextObject)
Reorders an object with respect to its siblings in the collection it belongs to. This is similar to using drag and drop in Form Builder to move a block in a list. This method represents a way to do the same thing programmatically. For example, if you want a block appear immediately before Block5 in a list, you pass the object representing Block5 as the nextObject argument.

Pass null to this method to move the object to the end of the list. If the specified object and the next_object do not share the same owner, or do not have the same type, the method throws an exception.

You cannot use this method to move objects between parents. For example, it cannot be used to move an Item from one Block to another. If you want to move an object from one parent to another you will have to do something like:

   //  to move 'itmA' to be positioned before 'itmB' in block
   // 'blkB' (when 'itmA' is in another block)

   // copy itmA into a new parent (blkB) using same name
   Item newItmA = itmA.clone(blkB, itmA.getName());
   newItmA.move(itmB);   // move new item relative to itmB
   itmA.destroy();       // delete original object
   itmA = newItmA;
 
Parameters:
nextObject - the object next to which the specified object is to be moved.
Throws:
JdapiException - if you attempt to move an object next to an object that does not share the same owner or is not of the same type.

getTypeId

public int getTypeId()
Returns the integer Forms object type that represents this object.
Returns:
the Forms object type for this object.
See Also:
queryType

queryType

public int queryType()
Returns the FormAPI object type ID (x_OTID in JdapiTypes). This should always be the same value as returned for getTypeId. The difference between the two methods is that queryType calls down to the API itself; this ensures that the correct type is returned. Because this method calls down to the API, you might find it a little faster to use getTypeID instead.
Returns:
x_OTID an object type ID as defined in JdapiTypes.

getClassName

public java.lang.String getClassName()
Returns the class name of the object. For example, it returns "Block" for a block object. This is useful if you want to refer to the name of the Forms object in your output but do not want to include the Java package details.
Returns:
name of "class" of Forms object.

getName

public java.lang.String getName()
Returns the name of this object. This is the same as the Name property (D2FP_NAME in JdapiTypes) of this object. For example, calling this method on a block:
 String blockName = myBlock.getName() 
 
could return a name such as "EMPLOYEES".

Note that not all Forms objects have names. If you call this method on one of these objects, then the string "<none>" is returned.

Returns:
name of the object.

getQualifiedName

public java.lang.String getQualifiedName(boolean includeModule)
Determines whether the fully-qualified name of the object is returned. For example, if includeModule is true, then this method returns a fully-qualified name for the object in the format: MODULE.OBJECT.CHILD.CHILD... where a dot (.) separates the names from the current object up to the module.

If includeModule is false, then this method returns the name for the object in the format: OBJECT.CHILD.CHILD... where the name of the module is dropped.

Parameters:
includeModule - true to include the module name with the object's fully-qualified name false to drop the module name.

getModule

public JdapiObject getModule()
Returns the module object that the current object refers to. For example, if you call getModule on a block, it returns a reference in memory to the module that owns the block. If there is no owning module, this method returns null.

The object returned by this method is synonymous to the MODULE_PTID object property in JdapiTypes.

Returns:
value of the property downcast to a JdapiObject; null if there is no owning module.

equals

public boolean equals(JdapiObject object)
Compares two objects and determines if they are equal.
Parameters:
object - object to be compared.
Returns:
true if the two objects are equal; returns false if they are not equal.

getOwner

public JdapiObject getOwner()
Returns the owner of the referred object. For example, if the referred object is an item, this method returns its owning block; if the object is a block, it returns its owning module, and so on.

If the referred object has no owner, then this method returns null.

Returns:
owner of the object; null if there is no owner

changeOwner

public void changeOwner(JdapiObject newOwner)
Assigns a new owner to the referred object. This method will cause any previous owner to relinquish its ownership of the referred object.

Set newOwner to null if you want the object to have no owner.

The only restriction on this method is that the new owner must be in the same module as the referred object. If you attempt to assign a new owner that is in a different module, then a JdapiException will be thrown.

Note: If you want to assign the object to a new owner in a different module, then you will have to clone or subclass the object.

Parameters:
newOwner - the new owner of referred object; specify null if you want the object to have no owner.
Throws:
JdapiException - if newOwner is in a different module.

getOwnedObjects

public JdapiIterator getOwnedObjects()
Returns an iterator over the list of objects that the referred object owns. For example, if the referred object is a block, this method will return an iterator over all of the items, triggers, relations, and so on, that the block owns.
Returns:
Iterator of JdapiObjects.

setClientInfo

public void setClientInfo(java.lang.Object clientInfo)
Sets the client information. Since the clientInfo is a java.lang.Object, the client information can be anything you want to associate with the referred object. For example, you can create your own class, then pass it to this method. The referred object will retain a reference to the clientInfo.

This client info object is not persistent and will be lost when the session ends.

Parameters:
clientInfo - client info to be associated with the object.

getClientInfo

public java.lang.Object getClientInfo()
Returns the client info object associated with this Object. The type ID of the object returned is dependant on what type ID of object was set using setClientObject.
Returns:
the client info object associated with this object.

getPersistentClientInfoBlob

public Blob getPersistentClientInfoBlob()
Returns the persistent client info Blob associated with this object.
Returns:
Blob containing client info.

getPersistentClientInfoObject

public java.lang.Object getPersistentClientInfoObject()
Returns the persistent client info Java object associated with this object.
Returns:
java.lang.Object serialized into the Forms object.

setPersistentClientInfo

public void setPersistentClientInfo(Blob val)
Sets persistent client info for this object.

Like the non-persistent client info methods, the client info can be any information that you want to save with the form. Unlike the non-persistent client info methods, the persistent info is saved as part of the form and will not be lost when the session is ended.

Parameters:
val - a Blob object containing client info.

setPersistentClientInfo

public void setPersistentClientInfo(java.io.Serializable val)
Serializes any Java object which supports the Serializable interface to this object's Persistent Client Info.

Like the non-persistent client info methods, the client info can be any information that you want to save with the form. Unlike the non-persistent client info methods, the persistent info is saved as part of the form and will not be lost when the session is ended.

Parameters:
val - any Serializable object containing client info.

isValidFormsObject

public boolean isValidFormsObject()
Determines whether this Java instance references a valid Forms object.

For example, assume that you have a reference to a block. If you call destroy() on its owning module, then the module and all of its blocks should be deleted from memory. The reference that you have no longer refers to a valid Forms object. A call to isValidFormsObject() on the block should return false.

Returns:
true if the instance references a valid forms object; false otherwise.

toString

public java.lang.String toString()
Converts and returns the object properties to string format. This is useful for debugging purposes.
Overrides:
toString in class java.lang.Object
Returns:
the string representation of the object.

getBooleanProperty

public boolean getBooleanProperty(int propertyTypeId)
Retrieves a boolean property from the referred object.
Parameters:
propertyTypeId - property type ID for which a boolean value is returned.
Returns:
the boolean property value.

getIntegerProperty

public int getIntegerProperty(int propertyTypeId)
Retrieves an integer property from the referred object. For example:
   ...
    if(propClass.hasProperty(propNumber) && propClass.allowGet(propNumber))
    {
      int propValue = propClass.getIntegerProperty(propNum);
    } 
    ...
 
Parameters:
propertyTypeId - property type ID for which an integer value is returned.
Returns:
the integer property value.

getStringProperty

public java.lang.String getStringProperty(int propertyTypeId)
Retrieves a string property from the referred object.
Parameters:
propertyTypeId - property type ID for which a string value is returned.
Returns:
the string property value.

getStringIDProperty

public int getStringIDProperty(int propertyTypeId)
Retrieves a special String ID (integer) property from the referred object.

This method is intended for use with the TranslationTable object only. For a given property ID it retrieves the integer that indexes the string property in the table for the current language.

Parameters:
propertyTypeId - property type ID for which a String ID value is returned.
Returns:
the integer String ID property value.

getObjectProperty

public JdapiObject getObjectProperty(int propertyTypeId)
Retrieves a JdapiObject property from the referred object. For example, if you pass the integer propertyTypeId for an Item in a Block to this method, it returns the Item.
Parameters:
propertyTypeId - property type ID for which a JdapiObject value is returned.
Returns:
the JdapiObject property value.

getChildObjectProperty

public JdapiIterator getChildObjectProperty(int propertyTypeId)
Retrieves child objects for a given property value. Implicit in this method is the idea of an ownership relationship between objects. Items are clearly owned by a Block. If you delete the Block, then its Items are deleted. On the other hand, Items can appear on a Canvas. If you delete the Canvas, however, the Items are not deleted. Thus, the method returns an iterator over Items if it is passed a Block. In contrast, if it is passed a Canvas, it should not return an iterator over Items.

For example:

      ...
      // get the actual values for the current child object type, 
      // for example, get the Items on a Block 
      iter = jo.getChildObjectProperty(prop.getPropertyId());  
      ...
 
Note, it should be (slightly) faster to call the specific method on the object, for example getBlocks() on the FormModule, as it involves fewer API calls. However, getChildObjectProperty should be sufficient if you only have a propertyTypeId available.

This method also differs from the direct accessors in that null is returned if there are no objects, not an empty iterator.

Parameters:
propertyTypeId - number identifying the child object property.
Returns:
Iterator for child objects, can return null if there are no child objects.

setBooleanProperty

public void setBooleanProperty(int propertyTypeId,
                               boolean propertyValue)
Sets the value of the specified boolean property belonging to the referred object.
Parameters:
propertyTypeId - property type ID of the property for which you want to set the boolean value.
propertyValue - the boolean value for the property.

setIntegerProperty

public void setIntegerProperty(int propertyTypeId,
                               int propertyValue)
Sets the value of the specified integer property belonging to the referred object.
Parameters:
propertyTypeId - property type ID of the property for which you want to set the integer value.
propertyValue - the integer value for the property.

setStringProperty

public void setStringProperty(int propertyTypeId,
                              java.lang.String propertyValue)
Sets the value of the specified string property for the object.
Parameters:
propertyTypeId - property type ID of the property for which you want to set the string value.
propertyValue - the string value for the property.

setObjectProperty

public void setObjectProperty(int propertyTypeId,
                              JdapiObject propertyValue)
Sets the value of the specified object property value for the object.
Parameters:
propertyTypeId - property type ID of the property for which you want to set the object property.
propertyValue - the object value for the property.

hasProperty

public boolean hasProperty(int propertyTypeId)
Determines if the referred object has the specified property. The method returns true if the object has the property identified by its propertyTypeId; false otherwise. For example:
      ...
   if(!pc.hasProperty(propertyId))    
      { 
        continue; // this property is not in the set 
      }
      ...
 
Parameters:
propertyTypeId - the number identifying the property.
Returns:
true if the object has that property, false otherwise.

isSubclassed

public boolean isSubclassed()
Determines whether the specified object has a subclassing parent.
Returns:
true if the specified object has an subclassing parent; false otherwise.

getSubclassParent

public JdapiObject getSubclassParent()
Returns the subclassing parent of the specified object.
Returns:
the subclassing parent, if the referred to object has no parent, null is returned.

setSubclassParent

public void setSubclassParent(JdapiObject parent)
Change the subclassing parent of the object referred.

The metadata associated with each object describes the types of objects that can become its subclassing parent. If the subclassing metadata associated with the refrred object doesn't indicate the objects of the given parent's type are allowed, then this method will throw an exception.

Parameters:
parent - The parent object. If this is null, the child the referred object will become an orphan. This is the way to unset the subclassing parent of an object.

createSubclassedChild

public JdapiObject createSubclassedChild(JdapiObject childOwner,
                                         java.lang.String childName)
Subclass the referred object. The child will be owned by the referred object specified.
Parameters:
childOwner - The object that will own the newly created subclassed child object.
childName - The name to be given to the newly created child.
Returns:
the subclassed object.

reattach

public void reattach()
Reattaches subclassed object. You must call this method if you manipulate any of the following properties of a Forms object: PARENT_MODULE_PTID, PARENT_NAME_PTID, PARENT_SL1OBJ_NAME_PTID, PARENT_MODULETYPE_PTID, PARENT_TYPE_PTID, PARENT_SL1OBJ_TYPE_PTID This is only if you are manipulating these low level subclassing properties.

hasOverriddenProperty

public boolean hasOverriddenProperty(int propertyTypeId)
Determine whether the object referred has a property of the given type id with an overridden value.
Parameters:
propertyTypeId - The type id of the property to be queried.
Returns:
TRUE if the object's property has overridden value, else FALSE.

hasInheritedProperty

public boolean hasInheritedProperty(int propertyTypeId)
Checks if a property is inherited.
Parameters:
propertyTypeId - Number that identified the property
Returns:
'true' if property is inherited

hasDefaultedProperty

public boolean hasDefaultedProperty(int propertyTypeId)
Checks if a property is set to it's default value.
Parameters:
propertyTypeId - Number that identified the property
Returns:
'true' if the property is set to the default value

getPropertyState

public int getPropertyState(int propertyTypeId)

A property can be in one of the 4 states.
DEFAULT_VALUE : has its default value
DEFAULT_VALUE_OVERRIDEN : locally overrides its default value
INHERITED_VALUE : inherits its ancestor's value
INHERITED_VALUE_OVERRIDDEN : locally overrides its ancestor's value

Return integer 1 through 4 representing one of the states.

Parameters:
propertyTypeId - The type id of the property.

getPropertyValueName

public java.lang.String getPropertyValueName(int propertyTypeId,
                                             int val)
Gets the string representation of a given property's value.
Parameters:
propertyTypeId - Property number
val - Value of property
Returns:
String representation

getIntegerPropertyString

public java.lang.String getIntegerPropertyString(int propertyTypeId)
Gets a numeric (long) property value's text representation.
Parameters:
propertyTypeId - Number identifying the property
Returns:
Property's text representation

inheritProperty

public void inheritProperty(int propertyTypeId)
Resets a property to it's default value (confusing name eh?). What it's really doing is setting the property to it's base classes value - i.e. whatever it's subclassed from. If the object is not subclassed from anything, then this is the default value.
Parameters:
propertyTypeId - Number that identified the property

getJdapiMetaObject

public JdapiMetaObject getJdapiMetaObject()
Gets the metadata object for the specified object.
Returns:
the metadata object for the specified object.

getMetaProperties

public JdapiIterator getMetaProperties()
Return an iterator over the meta properties in object referred.

The various property type ids and the object-property mapping are defined by the specific implementation in the respective Constants file.

Returns:
an enumeration of the specified object meta properties.