public class Jdapi
extends java.lang.Object
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.
Modifier and Type | Field and Description |
---|---|
(package private) static boolean |
s_clientData
Whether session was started with the clientData flag
|
(package private) static boolean |
s_noDecode
Whether session was started with the noDecode flag
|
(package private) static boolean |
s_transMode
Whether session was started with the transMode flag
|
Modifier and Type | Method and Description |
---|---|
protected static void |
addCacheListener(CacheListener l)
Add a cache listener.
|
(package private) static void |
addModule(JdapiModule module)
Adds a given module to the module list on this context.
|
protected static void |
addObject(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 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(CacheListener l)
Remove a cache listener.
|
(package private) static void |
removeModule(JdapiModule module)
Removes a given module from the module list on this context.
|
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.
|
static boolean s_clientData
static boolean s_noDecode
static boolean s_transMode
public static void startup(boolean clientData, boolean noDecode, boolean transMode)
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(); } }
clientData
- use client data modenoDecode
- Don't decode program units when loading modulestransMode
- Use the special tranlation servicessetFailLibraryLoad
,
setFailSubclassLoad
public static void shutdown()
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
.
public static java.lang.Object getClientContext()
setClientContext
public static void setClientContext(java.lang.Object clientContext)
getclientContext
to retrieve it from any part of your program.clientContext
- Object to set as the Jdapi client contextprotected static void initialize(boolean clientData, boolean noDecode, boolean transMode)
protected static long getContextPointer()
Calling this method for the first time in a session will implicitly cause the underlying JNI code to be initialised.
public static void connectToDatabase(java.lang.String connectString)
JdapiException
is thrown if connection
is unsuccessful.connectString
- database connection stringJdapiException
- if connection
is unsuccessfulpublic static boolean isConnectedToDatabase()
public static void disconnectFromDatabase()
Disconnecting from the database does not end the session. To end the session, use
shutdown
.
public static void setFailLibraryLoad(boolean val)
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
.
val
- if true, an exception will be suppressed if all of the libraries cannot
be found; if false
an exception will be thrown.public static void setFailSubclassLoad(boolean val)
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, see
startup
.
val
- Value to set flag topublic static java.lang.String[] getSubclassingDependencies(java.lang.String fileName)
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.
fileName
- name of file to get dependencies forpublic static java.lang.String[] getSubclassingDependencies(JdapiObject obj)
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.
obj
- the Forms object for which you want to get dependenciespublic static long getProductVersion()
public static java.util.Hashtable getBuiltIns()
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.protected static JdapiObject getObject(long pd2fob)
pd2fob
- C API pointer to Forms objectprotected static void addObject(BaseFormsObject obj)
obj
- Object to addstatic void addModule(JdapiModule module)
module
- Module to add to liststatic void removeModule(JdapiModule module)
module
- Module to remove from listpublic static JdapiIterator getModules()
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.
public static void destroyAllModules()
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.
protected static ContextCache getObjectCache()
protected static void dumpContextCache(java.io.PrintWriter out)
out
- Stream to output text toprotected static void purgeContextCache(boolean destroy)
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.
destroy
- Delete the object in Forms memory as well as Javaprotected static void purgeContextCacheModules(boolean destroy)
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.
destroy
- Delete the object in Forms memory as well as Javaprotected static void addCacheListener(CacheListener l)
l
- Listener to addprotected static void removeCacheListener(CacheListener l)
l
- Listener to remove