oracle.forms.jdapi
Class Jdapi

java.lang.Object
  |
  +--oracle.forms.jdapi.Jdapi

public class Jdapi
extends java.lang.Object

The Jdapi class provides the general context for all Jdapi applications.

The purpose of the Jdapi class is to manage sessions and contains client session-related methods, including object cache-related methods. All methods are static and can be called from any point in your code.

This class loads the underlying Forms stack and manages it in the background. The first time you call a method that has functionality, the Forms stack will be initialized automatically. There is no need to explicitly call the startup method unless you want to start Jdapi in something other than default mode.

There is an explicit shutdown method should programmers wish to free resources before the end of a process.

Typically, the methods in this class should not be overridden.


Method Summary
protected static void addCacheListener(oracle.forms.jdapi.CacheListener l)
          Add a cache listener.
protected static void addObject(oracle.forms.jdapi.BaseFormsObject obj)
          Registers an object as existing within this context, used internally.
static void connectToDatabase(java.lang.String connectString)
          Connects to the specified database.
static void destroyAllModules()
          WARNING: Destroys all modules loaded/created in the context.
static void disconnectFromDatabase()
          Disconnects from the database which the current session is connected to.
protected static void dumpContextCache(java.io.PrintWriter out)
          Dump the contents of the object cache to a stream for debugging purposes.
static java.util.Hashtable getBuiltIns()
          Retrieves all of the Forms-defined Built-Ins (PL/SQL program units).
static java.lang.Object getClientContext()
          Gets the client context handle passed during the startup.
protected static long getContextPointer()
          Get hold of the context pointer.
static JdapiIterator getModules()
          Returns an iterator over the modules loaded or created in this context.
protected static JdapiObject getObject(long pd2fob)
          Gets a Java representation of a Forms object by the C API pointer.
protected static oracle.forms.jdapi.ContextCache getObjectCache()
          Internal method to get the cache of objects that exist for this context.
static long getProductVersion()
          Gets the current version of the product.
static java.lang.String[] getSubclassingDependencies(JdapiObject obj)
          Gets the file names of modules that the specified Forms object subclasses from.
static java.lang.String[] getSubclassingDependencies(java.lang.String fileName)
          Returns an array of module file names that the specified file subclasses from.
protected static void initialize(boolean clientData, boolean noDecode, boolean transMode)
          Common initialization used on first access to BaseAPI methods.
static boolean isConnectedToDatabase()
          Returns whether the database connection exists.
protected static void purgeContextCache(boolean destroy)
          Purge the cache.
protected static void purgeContextCacheModules(boolean destroy)
          Purge any module objects from the cache.
protected static void removeCacheListener(oracle.forms.jdapi.CacheListener l)
          Remove a cache listener.
static void setClientContext(java.lang.Object clientContext)
          Sets the client context handle.
static void setFailLibraryLoad(boolean val)
          Determines whether an error will be thrown if there is a PL/SQL library load failure during a module load.
static void setFailSubclassLoad(boolean val)
          Determines whether an error will be thrown if all of the modules which a particular module subclasses from cannot be found when it is loaded.
static void shutdown()
          Explicitly terminates the Jdapi session and frees underlying resources without ending your process.
static void startup(boolean clientData, boolean noDecode, boolean transMode)
          Explicitly starts a session in a specialised mode.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

startup

public static void startup(boolean clientData,
                           boolean noDecode,
                           boolean transMode)
Explicitly starts a session in a specialised mode.

Jdapi initializes itself once you make a method call. There is no need to make an explicit call to startup() unless you want to initialize Jdapi in something other than default mode. Currently, Jdapi can be started only in default mode.

For example:

  import oracle.forms.jdapi.*; 

  // Jdapi.startup() does not need to be called because we are starting
  // the Jdapi in default mode.
   //
  public class JdapiSessionExample 
  { 
    public static void main(String[] args) 
    { 
       // suppress errors from missing subclassed modules 
       Jdapi.setFailSubclassLoad(true);
       // suppress errors from missing PLLs
       Jdapi.setFailLibraryLoad(true);

       // This line will cause initialisation
       FormModule. fmb = new FormModule("myform.fmb");
       // program code goes here
       ...
      // finally, free API resources
       Jdapi.shutdown(); 
     } 
  } 
 
Parameters:
clientData - use client data mode
noDecode - Don't decode program units when loading modules
transMode - Use the special tranlation services
See Also:
setFailLibraryLoad, setFailSubclassLoad

shutdown

public static void shutdown()
Explicitly terminates the Jdapi session and frees underlying resources without ending your process. This allows you to later restart the session, for example, after default initialisation has occurred, or simply to temporarily free resources if processing Forms is only a part of your running application.

You are free to shutdown and restart Jdapi as often as required, but multiple concurrent sessions are not supported and the API is single-threaded. Also, calling shutdown() destroys all the open Jdapi modules and objects.

For an example of shutdown(), see startup.


getClientContext

public static java.lang.Object getClientContext()
Gets the client context handle passed during the startup.
Returns:
the client context passed during startup. If no client context was passed during startup, this will return null.
See Also:
setClientContext

setClientContext

public static void setClientContext(java.lang.Object clientContext)
Sets the client context handle. This method can be used to attach an object containing any type of global data pertaining to the specific session. For example, use this method to attach an object containing the database connection information. You can then use getclientContext to retrieve it from any part of your program.
Parameters:
clientContext - Object to set as the Jdapi client context

initialize

protected static void initialize(boolean clientData,
                                 boolean noDecode,
                                 boolean transMode)
Common initialization used on first access to BaseAPI methods.

getContextPointer

protected static long getContextPointer()
Get hold of the context pointer. This is used internally by all JNI methods.

Calling this method for the first time in a session will implicitly cause the underlying JNI code to be initialised.

Returns:
C pointer to Forms context

connectToDatabase

public static void connectToDatabase(java.lang.String connectString)
Connects to the specified database. The database connection string typically has the format username/password@database. This method simply passes the string on to the underlying code--no error checking or validation is performed on the string. A JdapiException is thrown if connection is unsuccessful.
Parameters:
connectString - database connection string
Throws:
JdapiException - if connection is unsuccessful

isConnectedToDatabase

public static boolean isConnectedToDatabase()
Returns whether the database connection exists.
Returns:
true if the the database connection exists; false otherwise

disconnectFromDatabase

public static void disconnectFromDatabase()
Disconnects from the database which the current session is connected to. Disconnecting allows you to connect to another database. You can be connected to only one database at a time.

Disconnecting from the database does not end the session. To end the session, use shutdown.


setFailLibraryLoad

public static void setFailLibraryLoad(boolean val)
Determines whether an error will be thrown if there is a PL/SQL library load failure during a module load. When a module is loaded, all of its attached PL/SQL libraries are also loaded. If any of the libraries cannot be found, an error is thrown. This is the default behaviour.

If val is set to true, then the error will be suppressed. Note that references to missing libraries will be lost when you save the module.

If false, the error will be thrown. Note that it is safe to ignore these errors and save the form, since the missing references will not be lost. However, in these situations you may not be working with a complete representation of the Form application so you should use this mode with caution. For example, it may not be possible to compile the Form.

As an example of when you might want to set this method to true is if you have written a utility to inspect your forms objects for the value of a particular proprety. In this case, it does not matter if the libraries are loaded.

For an example of setFailLibraryLoad, see startup.

Parameters:
val - if true, an exception will be suppressed if all of the libraries cannot be found; if false an exception will be thrown.

setFailSubclassLoad

public static void setFailSubclassLoad(boolean val)
Determines whether an error will be thrown if all of the modules which a particular module subclasses from cannot be found when it is loaded.

When a module that includes subclassed objects is loaded, all of the modules that it subclasses from are also loaded. The API uses the FORMS90_PATH as the path to use to look for these modules. If any module fails to load, a JdapiException will be thrown (with a status code of 29). This is the default behaviour.

If val is set to true, then the error will be suppressed. Note that references to missing modules will be lost when you save the module.

If false, the error will be thrown and the Form will load as normal, but not all subclassing will be resolved. Note, it such situations you need to take care as you could damage your Form.

As an example of when you might want to set this method to true is if you have written a utility to inspect your forms objects for the value of a particular proprety. In this case, it does not matter if the subclassed objects are loaded.

For an example of setFailSubclassLoad, see startup.

Parameters:
val - Value to set flag to

getSubclassingDependencies

public static java.lang.String[] getSubclassingDependencies(java.lang.String fileName)
Returns an array of module file names that the specified file subclasses from. That is, the array contains the names of the files that the specified file needs to be be complete. For example, if you load the module represented by fileName, then this method will return the names of modules that will be loaded in the background.

If an empty array is returned, then there are no dependencies on the specified file.

Note that this method is not recursive. For example, assume that Form C subclasses from Form B and Form B subclasses from Form A. If you call this method on Form C, it will return information only on Form B. It will not reveal the dependence on Form A; the search for dependencies will go only 1-level deep. To discover the entire subclassing tree, you must call the method on Form B.

Parameters:
fileName - name of file to get dependencies for
Returns:
array of file names the module depends on. An empty array (0-length) will be returned if there are no dependencies.

getSubclassingDependencies

public static java.lang.String[] getSubclassingDependencies(JdapiObject obj)
Gets the file names of modules that the specified Forms object subclasses from. For example, you can pass a FormModule to this method and it will return the names of the other files it depends on for subclassing.

If an empty array is returned, then there are no dependencies on the specified file.

The difference between this method and getSubclassingDependencies(String filename) is that here you can pass in any object in a Form that has already been loaded. For example, if you pass a Block to this method, then an array of module names will be returned.

Note that this method is not recursive. It will return a list of dependencies only 1-level deep.

Parameters:
bfo - the Forms object for which you want to get dependencies
Returns:
array of file names the module depends on. An empty array (0-length) will be returned if there are no dependencies.

getProductVersion

public static long getProductVersion()
Gets the current version of the product.
Returns:
version of the product.

getBuiltIns

public static java.util.Hashtable getBuiltIns()
Retrieves all of the Forms-defined Built-Ins (PL/SQL program units). A Hashtable is returned, the keys (Strings) are the package names and the values are String arrays (Stirng[]) of the program units defined in those packages.
Returns:
Hashtable of packages

getObject

protected static JdapiObject getObject(long pd2fob)
Gets a Java representation of a Forms object by the C API pointer.
Parameters:
pd2fob - C API pointer to Forms object
Returns:
Java representation of that object

addObject

protected static void addObject(oracle.forms.jdapi.BaseFormsObject obj)
Registers an object as existing within this context, used internally.
Parameters:
obj - Object to add

getModules

public static JdapiIterator getModules()
Returns an iterator over the modules loaded or created in this context. All loaded and newly created modules are saved in the session module list.

For example:

 // get the module list from the session... 
      JdapiIterator mods = Jdapi.getModules(); 
      // ... and iterate around 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);
 

Note: this method does not get modules that may have been loaded internally by subclassing.

Returns:
Iterator of modules

destroyAllModules

public static void destroyAllModules()
WARNING: Destroys all modules loaded/created in the context. The modules are not removed from the file system, however they are removed from memory. If you have references to any of the modules they will now become invalid - so take care when using this!

For example, if you get a Block object from Module1 and then call destroyAllModules(), you will still have a reference to the Block, but the Block object will be invalid because it will be referencing invalid memory.


getObjectCache

protected static oracle.forms.jdapi.ContextCache getObjectCache()
Internal method to get the cache of objects that exist for this context.
Returns:
ContextCache of objects

dumpContextCache

protected static void dumpContextCache(java.io.PrintWriter out)
Dump the contents of the object cache to a stream for debugging purposes. This lets you see which Forms objects are currently held in the Java layer.
Parameters:
out - Stream to output text to

purgeContextCache

protected static void purgeContextCache(boolean destroy)
Purge the cache. This removes all objects from the cache.

You should only use this if you really know what's going on in the cache. In very few circumstances is it advisable to use this method.

Parameters:
destroy - Delete the object in Forms memory as well as Java

purgeContextCacheModules

protected static void purgeContextCacheModules(boolean destroy)
Purge any module objects from the cache. This removes any Form, Object Library or Menu modules from the cache.

You should only use this if you really know what's going on in the cache. In very few circumstances is it advisable to use this method. You may find this useful if you have an application that processes many modules. Between processing each module, call this method to clean up memory and release any auto-loaded modules you may not want. You don't have to do this, it just reduces memory usage.

Parameters:
destroy - Delete the object in Forms memory as well as Java

addCacheListener

protected static void addCacheListener(oracle.forms.jdapi.CacheListener l)
Add a cache listener.
Parameters:
l - Listener to add

removeCacheListener

protected static void removeCacheListener(oracle.forms.jdapi.CacheListener l)
Remove a cache listener.
Parameters:
l - Listener to remove