Interface JdapiObject

All Known Implementing Classes:
Alert, AttachedLibrary, Block, Canvas, CompoundText, Coordinate, DataSourceArgument, DataSourceColumn, Editor, Event, Font, FormModule, Graphics, Item, JdapiModule, LOV, LOVColumnMapping, Menu, MenuItem, MenuModule, ModuleParameter, ObjectGroup, ObjectGroupChild, ObjectLibrary, ObjectLibraryTab, PlsqlModule, Point, ProgramUnit, PropertyClass, RadioButton, RecordGroup, RecordGroupColumn, Relation, Report, TabPage, TextSegment, Trigger, VisualAttribute, VisualState, Window

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 Details

    • PROPERTY_STATE_UNKNOWN

      static final int PROPERTY_STATE_UNKNOWN
      Constant for unknown property state
      See Also:
    • PROPERTY_DEFAULT_VALUE

      static final int PROPERTY_DEFAULT_VALUE
      Constant for default property state
      See Also:
    • PROPERTY_OVERRIDDEN_DEFAULT_VALUE

      static final int PROPERTY_OVERRIDDEN_DEFAULT_VALUE
      Constant for overridden default property state
      See Also:
    • PROPERTY_INHERITED_VALUE

      static final int PROPERTY_INHERITED_VALUE
      Constant for inherited property state
      See Also:
    • PROPERTY_OVERRIDDEN_INHERITED_VALUE

      static final int PROPERTY_OVERRIDDEN_INHERITED_VALUE
      Constant for overridden inherited property state
      See Also:
  • Method Details

    • destroy

      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

      JdapiObject clone(JdapiObject parent, 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

      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 to 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

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

      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

      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

      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

      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

      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

      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

      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

      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

      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

      void setClientInfo(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

      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

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

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

      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

      void setPersistentClientInfo(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

      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

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

      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

      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

      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

      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

      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

      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

      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

      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

      void setStringProperty(int propertyTypeId, 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

      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

      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

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

      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

      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

      JdapiObject createSubclassedChild(JdapiObject childOwner, 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

      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

      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

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

      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

      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

      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

      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

      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

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

      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.