Class JdapiModule

java.lang.Object
oracle.forms.jdapi.JdapiModule
All Implemented Interfaces:
JdapiObject
Direct Known Subclasses:
FormModule, MenuModule, ObjectLibrary, PlsqlModule

public abstract class JdapiModule extends Object
This is the base object from which all Jdapi module objects are derived. JdapiModule is an abstract class and indirectly implements JdapiObject. This class provides methods for loading, managing, and referring generically to different module types.

The class is the supertype for all of the concrete module classes. The classes that define the different module types, FormModule, MenuModule, PlsqlModule, ObjectLibrary all extend JdapiModule.

The methods in JdapiModule let you work with modules generically. For example, you can write code to open modules in a list and refer to them as JdapiModule types. You do not have to worry about the specific type of module you are working with. For example:

     ...
     // get the module list from the session... 
         JdapiIterator mods = Jdapi.getModules(); 
         // ... and iterate round them 
         while(mods.hasNext()) 
         { 
           JdapiModule mod = (JdapiModule)mods.next(); 
           // getStringProperty(JdapiTypes.NAME_PTID) is equivalent to getName()
           String moduleName = mod.getName(); 
           System.out.println("Module Name: " + moduleName);
           ...
 
  • Field Details

    • m_pd2fob

      protected transient long m_pd2fob
      This is the d2fob pointer in the C ifjapi60 for the object that is derived from this class.
    • m_clientInfo

      protected transient Object m_clientInfo
      Client info object held against this Forms object.
  • Constructor Details

    • JdapiModule

      protected JdapiModule(long pd2fob)
      Constructor used by derived classes. If the object pointer is not null, the newly created object will register itself with the context to which it belongs.
      Parameters:
      pd2fob - C pointer to the Forms module object.
  • Method Details

    • getAbsolutePath

      public String getAbsolutePath()
      Returns the most recent location of this module on the file system. Modules are loaded from a specific path. Storing the absolute path is one technique that the system uses to ensure uniqueness between modules eventhough they might have the same file name. The path is updated every time the module is opened and saved. If you save the module somewhere else, the absolute path is updated.

      The method returns null if it is called on a newly created module. This is because the path is not set until the module is saved.

      Returns:
      the absolute path to the module; null for newly created modules.
    • setAbsolutePath

      protected void setAbsolutePath(String path)
      Sets the most recent location of this module on the file system.
      Parameters:
      path - String representing the location the file was opened from (or saved to) on the file system.
    • getModulesProductVersion

      public static long getModulesProductVersion(String fileName)
      Returns the product version used to create the specified module.
      Parameters:
      fileName - the file name of the module.
      Returns:
      version of the product used to create the module.
    • openModule

      public static JdapiModule openModule(String fileName)
      Loads a module from the file system. The module is returned cast as a JdapiModule object so that you can work with it generically.

      A runtime exception is thrown if a module the file has subclassed from cannot be found on the Forms path. This behaviour can be suppressed with the setFailSubclassLoad method.

      Parameters:
      fileName - file name of a module to load.
      Returns:
      a Forms module (FormModule, ObjectLibrary, MenuModule or PlsqlModule) cast as a JdapiModule.
    • openModule

      public static JdapiModule openModule(File f)
      Loads a module from the file system. The module is returned cast as a JdapiModule object so that you can work with it generically.

      A runtime exception is thrown if a module the file has subclassed from cannot be found on the Forms path. This behaviour can be suppressed with the setFailSubclassLoad method.

      Parameters:
      f - File object of module to load.
      Returns:
      a Forms module (FormModule, ObjectLibrary, MenuModule or PlsqlModule) cast as a JdapiModule.
    • openModule

      public static JdapiModule openModule(String fileName, String formsPath)
      Loads a module from the filesystem. The module is returned cast as a JdapiModule object so that you can work with it generically.

      A runtime exception is thrown if a module the file has subclassed from cannot be found on the Forms path. This behaviour can be suppressed with the setFailSubclassLoad method.

      Parameters:
      fileName - the file name of a module to load.
      formsPath - Path to use to look for modules that have been subclassed from. Pass null to this parameter to use the default FORMS90_PATH.
      Returns:
      a Forms module (FormModule, ObjectLibrary, MenuModule or PlsqlModule) cast as a JdapiModule.
    • openModule

      public static JdapiModule openModule(File f, String formsPath)
      Loads a module from the file system. The module is returned cast as a JdapiModule object so that you can work with it generically.

      A runtime exception is thrown if a module the file has subclassed from cannot be found on the Forms path. This behaviour can be suppressed with the setFailSubclassLoad() method.

      Parameters:
      f - the file object of the module to load.
      formsPath - path to use to look for modules that have been subclassed from. Pass null to this parameter to use the default FORMS90_PATH.
      Returns:
      a Forms module (FormModule, ObjectLibrary, MenuModule or PlsqlModule) cast as a JdapiModule.
    • save

      public abstract void save(String fileName)
      Saves the module instance to the file system. If you simply provide a file name such as module1 or module.fmb, then the file is saved to the current directory. If you enter a path and the pathname is an invalid String for that system, then a error will be returned.

      Beecause this is a String, there might be an issue with directory separators. On Windows systems you will have to use a double backslash (\\); the first backslash acts as the "escape" character. There should not be a problem with the forward slash.

      Parameters:
      fileName - the file path or name that you want to use to save the module.
    • compile

      public abstract void compile()
      Compiles the module instance to the file system. This is a placeholder so that it can be overidden in the module classes that subclass JdapiModule.
    • compile_all

      public void compile_all()
      Compiles all the pl/sql in the module. This is equivalent to choosing compile_all in the Forms Builder. This is only supported for Forms and Menus, not Libraries.
    • destroy

      public void destroy()
      Destroys the object - this removes the object from its context. The JNI level is responsible for removing this object from the context cache, so we don't need to do that in here.
      Specified by:
      destroy in interface JdapiObject
    • getTypeId

      public abstract int getTypeId()
      Returns the integer Forms object type that represents this object.
      Specified by:
      getTypeId in interface JdapiObject
      Returns:
      the Forms object type for this object.
      See Also:
    • getObjectPointer

      protected long getObjectPointer()
      Gets the Forms API pointer for this object.
      Returns:
      C pointer to the Forms object
    • 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.
      Specified by:
      queryType in interface JdapiObject
      Returns:
      x_OTID an object type ID as defined in JdapiTypes.
    • setClientInfo

      public 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.

      Specified by:
      setClientInfo in interface JdapiObject
      Parameters:
      clientInfo - client info to be associated with the object.
    • getClientInfo

      public Object getClientInfo()
      Returns the client info object associated with this Object. The type ID of the object returned is dependant on the type ID of the object that was set using setClientObject.
      Specified by:
      getClientInfo in interface JdapiObject
      Returns:
      the client info object associated with this object.
    • getPersistentClientInfoBlob

      public Blob getPersistentClientInfoBlob()
      Returns the persistent client info Blob associated with this object.
      Specified by:
      getPersistentClientInfoBlob in interface JdapiObject
      Returns:
      Blob containing client info.
    • getPersistentClientInfoObject

      public Object getPersistentClientInfoObject()
      Returns the persistent client info Java object associated with this object.
      Specified by:
      getPersistentClientInfoObject in interface JdapiObject
      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.

      Specified by:
      setPersistentClientInfo in interface JdapiObject
      Parameters:
      val - a Blob object containing client info.
    • setPersistentClientInfo

      public void setPersistentClientInfo(Serializable obj)
      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.

      Specified by:
      setPersistentClientInfo in interface JdapiObject
      Parameters:
      obj - any Serializable object containing client info.
    • equals

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

      public 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.

      It is your reponsibility to pass in an appropriate parent object. If you do not do this, you will probably get a JdapiException runtime exception. If possible, use the type safe clone method that is provided on each Forms object class.

      Specified by:
      clone in interface JdapiObject
      Parameters:
      parent - owner of the new object.
      newName - name of the new object.
      Returns:
      the clone of the object.
    • 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.

      Specified by:
      changeOwner in interface JdapiObject
      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.
    • toString

      public String toString()
      Converts and returns the object properties to string format. This is useful for debugging purposes. The string is in the format: NAME(CLASSNAME, pointer: D2FOB*, context D2FCTX*)
      Specified by:
      toString in interface JdapiObject
      Overrides:
      toString in class Object
      Returns:
      String representation of the object
    • clearObjectPointer

      protected void clearObjectPointer()
      Used internally to flag this object as an invalid object.
    • isValidFormsObject

      public boolean isValidFormsObject()
      Description copied from interface: JdapiObject
      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.

      Specified by:
      isValidFormsObject in interface JdapiObject
      Returns:
      true if the instance references a valid forms object; false otherwise.
    • move

      public void move(JdapiObject next)
      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:

         // e.g. 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;
       
      Specified by:
      move in interface JdapiObject
      Parameters:
      next - 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 samme type.
    • getBooleanProperty

      public boolean getBooleanProperty(int propertyTypeId)
      Retrieves a boolean property from the referred object.
      Specified by:
      getBooleanProperty in interface JdapiObject
      Parameters:
      propertyTypeId - property type ID for which a boolean value is returned.
      Returns:
      the boolean property value.
    • getStringProperty

      public String getStringProperty(int propertyTypeId)
      Retrieves a string property from the referred object.
      Specified by:
      getStringProperty in interface JdapiObject
      Parameters:
      propertyTypeId - property type ID for which a string value is returned.
      Returns:
      the string 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);
          } 
          ...
       
      Specified by:
      getIntegerProperty in interface JdapiObject
      Parameters:
      propertyTypeId - property type ID for which an integer value is returned.
      Returns:
      the integer 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.

      Specified by:
      getStringIDProperty in interface JdapiObject
      Parameters:
      propertyTypeId - property type ID for which a String ID value is returned.
      Returns:
      the integer String ID property value.
    • getPropertyValueName

      public String getPropertyValueName(int propertyTypeId, int val)
      Description copied from interface: JdapiObject
      Gets the string representation of a given property's value.
      Specified by:
      getPropertyValueName in interface JdapiObject
      Parameters:
      propertyTypeId - Property number
      val - Value of property
      Returns:
      String representation
    • getIntegerPropertyString

      public String getIntegerPropertyString(int propertyTypeId)
      Description copied from interface: JdapiObject
      Gets a numeric (long) property value's text representation.
      Specified by:
      getIntegerPropertyString in interface JdapiObject
      Parameters:
      propertyTypeId - Number identifying the property
      Returns:
      Property's text representation
    • getObjProp

      protected long getObjProp(int propertyTypeId)
      Internal method used to get an object property value. This only really gets the C pointer to the Forms object. You must then use the ContextCache to lookup/instantiate the Java representation of the object.
      Parameters:
      propertyTypeId - Number identifying the property
      Returns:
      Property's value
      See Also:
    • getObjectProperty

      public JdapiObject getObjectProperty(int propertyTypeId)
      Description copied from interface: JdapiObject
      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.
      Specified by:
      getObjectProperty in interface JdapiObject
      Parameters:
      propertyTypeId - property type ID for which a JdapiObject value is returned.
      Returns:
      the JdapiObject property value.
    • getChildObjectProperty

      public JdapiIterator getChildObjectProperty(int propertyTypeId)
      Description copied from interface: JdapiObject
      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.

      Specified by:
      getChildObjectProperty in interface JdapiObject
      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)
      Description copied from interface: JdapiObject
      Sets the value of the specified boolean property belonging to the referred object.
      Specified by:
      setBooleanProperty in interface JdapiObject
      Parameters:
      propertyTypeId - property type ID of the property for which you want to set the boolean value.
      propertyValue - the boolean value for the property.
    • setStringProperty

      public void setStringProperty(int propertyTypeId, String propertyValue)
      Description copied from interface: JdapiObject
      Sets the value of the specified string property for the object.
      Specified by:
      setStringProperty in interface JdapiObject
      Parameters:
      propertyTypeId - property type ID of the property for which you want to set the string value.
      propertyValue - the string value for the property.
    • setIntegerProperty

      public void setIntegerProperty(int propertyTypeId, int propertyValue)
      Sets the value of the specified object integer property.
      Specified by:
      setIntegerProperty in interface JdapiObject
      Parameters:
      propertyTypeId - property type id for which we set the integer value.
      propertyValue - the integer property value in property.
    • setObjProp

      protected void setObjProp(int propertyTypeId, long val)
      Internal method used to set an object property. This sets the object property by the C pointer to the object you want to set.
      Parameters:
      propertyTypeId - Number identifying the property
      val - Value to set the property to
      See Also:
    • setObjectProperty

      public void setObjectProperty(int propertyTypeId, JdapiObject propertyValue)
      Sets the value of the specified object object property value.
      Specified by:
      setObjectProperty in interface JdapiObject
      Parameters:
      propertyTypeId - property type id for which we set the object property value.
      propertyValue - the object property value in property.
    • hasProperty

      public boolean hasProperty(int propertyTypeId)
      Checks if the object has a given property.
      Specified by:
      hasProperty in interface JdapiObject
      Parameters:
      propertyTypeId - Number identifying the property
      Returns:
      'true' if the object has that property, 'false' otherwise
    • 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.
      Specified by:
      inheritProperty in interface JdapiObject
      Parameters:
      propertyTypeId - Number that identified the property
    • hasInheritedProperty

      public boolean hasInheritedProperty(int propertyTypeId)
      Checks if a property is inherited.
      Specified by:
      hasInheritedProperty in interface JdapiObject
      Parameters:
      propertyTypeId - Number that identified the property
      Returns:
      'true' if property is inherited
    • hasOverriddenProperty

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

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

      public int getPropertyState(int propertyTypeId)
      Returns the current state of the specified property.

      A property can be in one of the 5 states:
      PROPERTY_STATE_UNKNOWN = 0;
      PROPERTY_DEFAULT_VALUE = 1;
      PROPERTY_OVERRIDDEN_DEFAULT_VALUE = 2;
      PROPERTY_INHERITED_VALUE = 3;
      PROPERTY_OVERRIDDEN_INHERITED_VALUE = 3;

      Specified by:
      getPropertyState in interface JdapiObject
      Parameters:
      propertyTypeId - The type id of the property.
      Returns:
      integer 0 through 3 representing one of the states.
    • isSubclassed

      public boolean isSubclassed()
      Checks if the object is subclassed from another object.
      Specified by:
      isSubclassed in interface JdapiObject
      Returns:
      'true' if the object is subclassed, 'false' otherwise
    • getSubclassParent

      public JdapiObject getSubclassParent()
      Get Source (SOURCE_PTID) object property, i.e. the object this object subclassed from. This is also implemented on derived classed with this property as getSource().
      Specified by:
      getSubclassParent in interface JdapiObject
      Returns:
      Value of property downcast to a BaseFormsObject (null if none of object does not have this property)
    • 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.

      Specified by:
      setSubclassParent in interface JdapiObject
      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.
    • unsetSubclassParent

      public void unsetSubclassParent()
      Remove the subclassing parent of the object referred.

      The subclassing will be removed completely if it existed and the object will now contain the default values.

    • createSubclassedChild

      public JdapiObject createSubclassedChild(JdapiObject childOwner, String childName)
      Subclass the referred object. The child will be owned by the referred object specified.
      Specified by:
      createSubclassedChild in interface JdapiObject
      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: PAR_MODULE_PTID, PAR_NAM_PTID, PAR_SL1OBJ_NAM_PTID, PAR_MODTYP_PTID, PAR_TYP_PTID, PARSL1OBJ_TYP_PTID This is only if you are manipulating these low level subclassing properties.
      Specified by:
      reattach in interface JdapiObject
    • getModule

      public JdapiObject getModule()
      Get Module (MODULE_PTID) object property.
      Specified by:
      getModule in interface JdapiObject
      Returns:
      Value of property downcast to a JdapiObject (null if none)
    • getOwner

      public JdapiObject getOwner()
      Get Owner (OWNER_PTID) object property.
      Specified by:
      getOwner in interface JdapiObject
      Returns:
      Value of property downcast to a JdapiObject (null if none)
    • getOwnedObjects

      public JdapiIterator getOwnedObjects()
      Get the object instances owned by this particular object.
      Specified by:
      getOwnedObjects in interface JdapiObject
      Returns:
      Iterator of JdapiObjects
    • getName

      public String getName()
      Get the Name property (NAME_PTID) of this object. Not all Forms objects have names and if this is the case then the string "<none>" is returned.
      Specified by:
      getName in interface JdapiObject
      Returns:
      Name of object
    • getClassName

      public String getClassName()
      Gets the class name of the object. This is useful if you want to refer to the name of the Forms object in some output but don't want the Java package details.
      Specified by:
      getClassName in interface JdapiObject
      Returns:
      Name of "class" of Forms object
    • getQualifiedName

      public String getQualifiedName(boolean includeModule)
      Gets a fully qualified name for the object in the format of: MODULE.OBJECT.CHILD.CHILD... i.e. '.' separates the objects names from the current object back upto the module.

      Specified by:
      getQualifiedName in interface JdapiObject
      Parameters:
      includeModule - Include the module name
    • getJdapiMetaObject

      public JdapiMetaObject getJdapiMetaObject()
      Gets the metadata object for the specified object.
      Specified by:
      getJdapiMetaObject in interface JdapiObject
      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.

      Specified by:
      getMetaProperties in interface JdapiObject
      Returns:
      an enumeration of the specified object meta properties.