Class Jdapi
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
Modifier and TypeMethodDescriptionprotected 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
(String connectString) Connects to the specified database.static void
WARNING: Destroys all modules loaded/created in the context.static void
Disconnects from the database which the current session is connected to.protected static void
Dump the contents of the object cache to a stream for debugging purposes.static Hashtable
Retrieves all of the Forms-defined Built-Ins (PL/SQL program units).static Object
Gets the client context handle passed during the startup.protected static long
Get hold of the context pointer.static JdapiIterator
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
Internal method to get the cache of objects that exist for this context.static long
Gets the current version of the product.static String[]
getSubclassingDependencies
(String fileName) Returns an array of module file names that the specified file subclasses from.static String[]
Gets the file names of modules that the specified Forms object subclasses from.protected static void
initialize
(boolean clientData, boolean noDecode, boolean transMode) Common initialization used on first access to BaseAPI methods.static boolean
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
(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.
-
Method Details
-
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 modenoDecode
- Don't decode program units when loading modulestransMode
- Use the special tranlation services- See Also:
-
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()
, seestartup
. -
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
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 usegetclientContext
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
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. AJdapiException
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
, seestartup
.- Parameters:
val
- iftrue
, an exception will be suppressed if all of the libraries cannot be found; iffalse
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 FORMS_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
, seestartup
.- Parameters:
val
- Value to set flag to
-
getSubclassingDependencies
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 byfileName
, 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
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:
obj
- 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
Retrieves all of the Forms-defined Built-Ins (PL/SQL program units). AHashtable
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
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
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
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
-