|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.intersys.cache.jni.CacheJNI
Interface for calling into Cache' from Java programs. This can only be used
from Java programs which have been invoked via the Cache'->Java linkage
provided by the $SYSTEM.Java methods. These programs are running in a JVM
loaded by Cache', created using $SYSTEM.Java.InitVM(). This class cannot
be used to connect "standalone" java applications or applets to Cache'; use
one of the IP based connections for that situation.
isLoaded()
indicates whether the other methods of this class can be
used or not. Calling a method of this class when isLoaded()
returns
false will result in a java.lang.UnsatisfiedLinkError error.
Multi-threaded Java Applications and Cache'
Philosophically the design of software which uses this class follows one
of two patterns: Applications where the Java code is viewed as a subroutine
of a Cache' and the inverse where Cache' is viewed as a
service provider to a Java application. There isn't any fundamental
difference between these two but software which is primarily a
Java application using the services of the Cache' database may have to
worry about multithreading issues. This can be an issue for Cache
applications which call out to Java but that is much less likely.
The issue is that Cache is not re-entrent and only one Java thread
at a time can make use of the CacheJNI interface. It is not enough
to simply declare the CacheJNI methods as synchronized because the
scope of the required synchronization is greater than just a single
CacheJNI method call. Consider the case of a thread which wants to retrieve
a global reference from Cache'. This thread must block other threads
from the time it starts setting up the call stack with PushGlobal()
until it completes the operation with a call to one of the CacheJNI.Pop
methods to retrieve the result left on the stack by GetGlobal().
It is the Java programmer's
responsibility to arbitrate access to the CacheJNI methods among Java
threads and to ensure that the CacheJNI methods are not used
while a process is executing within Cache. An example of the latter would
be a Cache' program that starts a Java thread and returns to run "in
Cache'" while the Java thread continues in Java. If the Java thread wants
to call into Cache' it must wait for the Cache' thread to call back into
Java. The consequenses of violating these rules can be disasterous. At
best they can result in memory violations which will terminate the Cache
process, and the Java Virtual Machine. At worst they can result in
Cache' system hangs, requiring a Cache' restart, or Cache' database
degradation.
A Java application which views Cache as a service can deal with these issues using the
Java synchronized statement or method to arbitrate use of this
interface. For a Cache' program which makes use of Java as a service it
would be better to define a messaging interface between the
Java threads and the Cache' program where the Java threads post messages
to a queue which the Cache' side of the application pulls off
with the $SYSTEM.Java methods.
Field Summary | |
static int |
CACHE_ERBADARG
Error code indicating an argument to a method is out of range or otherwise invalid. |
static int |
CACHE_ERINTERRUPT
Error code returned if operations is interrupted by a CTRL/C |
static int |
CACHE_ERNOCON
Error code returned from an attempt to access Cache' when the process is already executing in "Cache' context". |
static int |
CACHE_ERNORES
Error code indicating a function was called to pop an argument off of the argument stack but no argument was present to be popped. |
static int |
CACHE_ERRETTOOSMALL
Error code indicating that the return buffer is too small and nothing has been returned |
static int |
CACHE_ERRETTRUNC
Error code indicating that the return buffer was too small so only a portion of the requested item was returned. |
static int |
CACHE_ERSTRTOOLONG
Error code returned if a string argument is too long |
static int |
CACHE_ERUNKNOWN
Error code returned from the routines that translate error codes into text ErrorMessage(int) that indicates that the specified error
code is not valid. |
static int |
CACHE_TYPE_DOUBLE
When returned from TopArgType() means the argument is a 64bit floating
point number. |
static int |
CACHE_TYPE_INT
When returned from TopArgType() means the argument is a 32bit integer. |
static int |
CACHE_TYPE_OREF
Returned from TopArgType() to indicate that the next item to pop
is an internal Cache' object id. |
static int |
CACHE_TYPE_STRING
Returned from TopArgType() to indicate that the next item to pop
is a Cache' string. |
Constructor Summary | |
CacheJNI()
|
Method Summary | |
static void |
CallFunction(int rtnflags,
int narg)
Call the function specified by PushFunction() using the arguments stacked with the PushArg methods and get a value back. |
static void |
DoFunction(int rtnflags,
int narg)
Execute the function specified by PushFunction() as a routine (discard the return value) passing the arguments stacked with the PushArg methods. |
static void |
DoRoutine(int rtnflags,
int narg)
Call the routine specified by PushRoutine() passing the arguments stacked with the PushArg methods. |
static String |
ErrorMessage(int code)
Return the text of the error message associated with the specified code. |
static void |
Evaluate(String cmd)
Evaluate a COS expression as if it was specified on the right hand side of an equals sign. |
static void |
Execute(String cmd)
Execute a COS statement as if it was passed to the COS Execute command. |
static void |
GetGlobal(int narg,
int undefok)
Retrieves the value of the global reference specified by PushGlobal() and PushArg(). |
static void |
GetLocal(String name)
Retrieves the value of the specified local variable. |
static void |
getLock()
Returns with the lock on the class monitor that prevents multiple threads from using the native methods of this class at the same time. |
static void |
GetProperty()
Retrieve the value of a class property. |
static void |
InvokeClassMethod(int narg)
Execute the class method specified by PushClassMethod() passing the arguments set up with the PushArg methods. |
static void |
InvokeMethod(int narg)
Execute an instance method specified by PushMethod() passing the arguments set up with the PushArg methods. |
static boolean |
isLoaded()
Tests whether this class can be used to access Cache' from a Java program. |
static void |
main(String[] str)
|
static CacheInternalArg |
Pop()
Removes the argument on the top of the Cache' argument stack which would be something returned from one of the functions in this class that return data from Cache' back to Java such as CallFunction(int,int) or
GetGlobal(int,int) . |
static double |
PopDouble()
Returns the argument on the top of the Cache' argument stack as a double. |
static float |
PopFloat()
Returns the argument on the top of the Cache' argument stack as a float. |
static int |
PopInt()
Returns the argument on the top of the Cache' argument stack as an integer. |
static CacheExternalOref |
PopOref()
Used when the argument on top of the Cache' argument stack is an internal Cache' object id. |
static String |
PopString()
Returns the argument on the top of the Cache' argument stack as a string. |
static void |
PushArg(CacheExternalOref oref)
Pushes an integer onto the Cache' argument stack as a Cache' object reference id. |
static void |
PushArg(double dblarg)
Pushes a double onto the Cache' argument stack as a Cache' floating point number. |
static void |
PushArg(float floatarg)
Pushes a float onto the Cache' argument stack as a Cache' floating point number. |
static void |
PushArg(int intarg)
Pushes an integer onto the Cache' argument stack as a Cache' integer. |
static void |
PushArg(String strarg)
Pushes a string onto the Cache' argument stack as a Cache' string. |
static void |
PushClassMethod(String classname,
String methodname,
int returnrequired)
Pushes the name of a Class (static) method in preparation for calling it. |
static int |
PushFunction(String name)
Pushes the name of a COS Function in order to execute it either as a function (return the result on the argument stack) or as a routine (discard the return value). |
static int |
PushFunction(String tag,
int offset,
String environment,
String name)
Pushes the name of a COS Function in order to execute it either as a function (return the result on the argument stack) or as a routine (discard the return value). |
static int |
PushFunction(String tag,
String name)
Pushes the name of a COS Function in order to execute it either as a function (return the result on the argument stack) or as a routine (discard the return value). |
static void |
PushGlobal(String gloname)
Pushes the Global name portion of a global reference in preparation for calling SetGlobal or GetGlobal to perform a global reference in the current namespace. |
static void |
PushGlobal(String gloname,
String env)
Pushes the Global name and environment portions of a global reference in preparation for calling SetGlobal or GetGlobal. |
static void |
PushMethod(CacheExternalOref oref,
String methodname,
int returnrequired)
Pushes the name of an instance method in preparation for calling it. |
static void |
PushProperty(CacheExternalOref oref,
String propertyname)
Pushes a property name with class reference in preparation for calling SetProperty or GetProperty. |
static int |
PushRoutine(String name)
Pushes the name of a COS Routine in order to call it. |
static int |
PushRoutine(String tag,
int offset,
String environment,
String name)
Pushes the name of a COS Routine in order to call it. |
static int |
PushRoutine(String tag,
String name)
Pushes the name of a COS Routine in order to call it. |
static boolean |
releaseLock()
Releases the lock on the class monitor that my be blocking other threads from using this class. |
static void |
SetGlobal(int narg)
Sets the value of the global reference specified by PushGlobal() and PushArg(). |
static void |
SetLocal(String name)
Sets the value of the specified local variable. |
static void |
SetProperty()
Sets the the value of a class property. |
static int |
TopArgType()
Return the type of the top argument on the Cache' argument stack, if its a valid argument. |
static void |
UnPop()
Decrements the internal Cache' argument stack pointer which pushes the last argument popped back onto the argument stack |
Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static final int CACHE_TYPE_INT
TopArgType()
means the argument is a 32bit integer.
public static final int CACHE_TYPE_DOUBLE
TopArgType()
means the argument is a 64bit floating
point number.
public static final int CACHE_TYPE_STRING
TopArgType()
to indicate that the next item to pop
is a Cache' string. On non-Unicode Cache' systems, this is a string of
8-bit bytes. On UNICODE systems, this is a string of 16-bit characters.
When returned into a Java String, all Cache strings are converted to
Unicode.
public static final int CACHE_TYPE_OREF
TopArgType()
to indicate that the next item to pop
is an internal Cache' object id.
public static final int CACHE_ERNORES
public static final int CACHE_ERBADARG
public static final int CACHE_ERRETTRUNC
public static final int CACHE_ERUNKNOWN
ErrorMessage(int)
that indicates that the specified error
code is not valid.
public static final int CACHE_ERRETTOOSMALL
public static final int CACHE_ERNOCON
public static final int CACHE_ERINTERRUPT
public static final int CACHE_ERSTRTOOLONG
Constructor Detail |
public CacheJNI()
Method Detail |
public static void main(String[] str)
public static boolean isLoaded()
public static void getLock()
public static boolean releaseLock()
public static void PushArg(float floatarg) throws CallinException
floatarg
- 32bit floating point number to push
CallinException
public static void PushArg(int intarg) throws CallinException
intarg
- 32bit integer to push
CallinException
public static void PushArg(double dblarg) throws CallinException
dblarg
- 64bit floating point number to push
CallinException
public static void PushArg(CacheExternalOref oref) throws CallinException, ObjectClosedException
oref
- Reference to a Cache' object being pushed on the stack
as an argument.
CallinException
ObjectClosedException
public static void PushArg(String strarg) throws CallinException, CacheException
strarg
- string to push
CallinException
CacheException
public static void PushGlobal(String gloname) throws CallinException, CacheException
gloname
- the global name (without leading "^") to push
CallinException
CacheException
SetGlobal(int)
,
GetGlobal(int, int)
public static void PushGlobal(String gloname, String env) throws CallinException, CacheException
gloname
- the global name (without leading "^") to pushenv
- environment string of the form "namespace" or
"^remote system^directory".
CallinException
CacheException
SetGlobal(int)
,
GetGlobal(int, int)
public static void PushProperty(CacheExternalOref oref, String propertyname) throws CallinException, CacheException, ObjectClosedException
oref
- object reference of the class containing the propertypropertyname
- name of the property to work with
CallinException
CacheException
ObjectClosedException
SetProperty()
,
GetProperty()
public static void PushMethod(CacheExternalOref oref, String methodname, int returnrequired) throws CallinException, CacheException, ObjectClosedException
oref
- object reference id of the class containing the methodmethodname
- name of the method to callreturnrequired
- 0 means that the method does not need to return a
value. 1 means that it does (eg. via a COS argumented quit command) or
else a <COMMAND> error will be generated.
CallinException
CacheException
ObjectClosedException
InvokeMethod(int)
public static void PushClassMethod(String classname, String methodname, int returnrequired) throws CallinException, CacheException
classname
- name of the class containing the static methodmethodname
- name of the method to callreturnrequired
- 0 means that the method does not need to return a
value. 1 means that it does (eg. via a COS argumented quit command) or
else a <COMMAND> error will be generated.
CallinException
CacheException
InvokeClassMethod(int)
public static int PushRoutine(String name) throws CacheException, CallinException
name
- Name of the routine to call in the current namespace.
CacheException
CallinException
DoRoutine(int, int)
public static int PushRoutine(String tag, String name) throws CacheException, CallinException
name
- Name of the routine to call in the current namespace.tag
- tag to begin executation at
CacheException
CallinException
DoRoutine(int, int)
public static int PushRoutine(String tag, int offset, String environment, String name) throws CacheException, CallinException
name
- Name of the routine to call in the current namespace.tag
- tag which is the base of the offset in finding the first
line of the routine to execute.offset
- numeric offset from tag to being executation at
CacheException
CallinException
DoRoutine(int, int)
public static int PushFunction(String name) throws CacheException, CallinException
name
- Name of the routine to call in the current namespace.
CacheException
CallinException
DoFunction(int, int)
,
CallFunction(int, int)
public static int PushFunction(String tag, String name) throws CacheException, CallinException
name
- Name of the routine to call in the current namespace.tag
- tag to begin executation at
CacheException
CallinException
DoFunction(int, int)
,
CallFunction(int, int)
public static int PushFunction(String tag, int offset, String environment, String name) throws CacheException, CallinException
name
- Name of the routine to call in the current namespace.tag
- tag which is the base of the offset in finding the first
line of the routine to execute.offset
- numeric offset from tag to being executation at
CacheException
CallinException
DoFunction(int, int)
,
CallFunction(int, int)
public static void UnPop() throws CallinException
CallinException
public static CacheInternalArg Pop() throws CallinException
CallFunction(int,int)
or
GetGlobal(int,int)
. The other Pop<type> methods which
return the top argument convert
it to the specified type. This method returns an opaque structure
that can be used to examine the Cache' type of the data and retrieve
it in whatever format is required.
CallinException
public static int PopInt() throws CallinException
CallinException
public static float PopFloat() throws CallinException
CallinException
public static double PopDouble() throws CallinException
CallinException
public static String PopString() throws CallinException
CallinException
public static CacheExternalOref PopOref() throws CallinException
CallinException
CacheExternalOref
public static void DoRoutine(int rtnflags, int narg) throws CallinException
rtnflags
- value returned from PushRoutinenarg
- the number of arguments which are being passed to the
routine.
CallinException
PushRoutine(String)
,
PushRoutine(String,String)
,
PushRoutine(String,int,String,String)
,
PushArg(String)
,
PushArg(int)
,
PushArg(float)
,
PushArg(double)
public static void DoFunction(int rtnflags, int narg) throws CallinException
rtnflags
- value returned from PushFunctionnarg
- the number of arguments which are being passed to the
function.
CallinException
PushFunction(String)
,
PushFunction(String, String)
,
PushFunction(String, int, String, String)
,
PushArg(String)
,
PushArg(int)
,
PushArg(float)
,
PushArg(double)
public static void CallFunction(int rtnflags, int narg) throws CallinException
rtnflags
- value returned from PushFunctionnarg
- the number of arguments which are being passed to the
function.
CallinException
PushFunction(String)
,
PushFunction(String, String)
,
PushFunction(String, int, String, String)
,
PushArg(String)
,
PushArg(int)
,
PushArg(float)
,
PushArg(double)
public static void InvokeClassMethod(int narg) throws CallinException
narg
- the number of arguments which are being passed to the
class method.
CallinException
PushClassMethod(String, String, int)
,
PushArg(String)
,
PushArg(int)
,
PushArg(float)
,
PushArg(double)
public static void InvokeMethod(int narg) throws CallinException
narg
- the number of arguments which are being passed to the
instance method.
CallinException
PushMethod(CacheExternalOref, String, int)
,
PushArg(String)
,
PushArg(int)
,
PushArg(float)
,
PushArg(double)
public static void GetProperty() throws CallinException
CallinException
PushProperty(CacheExternalOref, String)
public static void SetProperty() throws CallinException
CallinException
PushProperty(CacheExternalOref, String)
public static void GetLocal(String name) throws CallinException, CacheException
CallinException
CacheException
public static void SetLocal(String name) throws CallinException, CacheException
CallinException
CacheException
PushArg(String)
,
PushArg(int)
,
PushArg(float)
,
PushArg(double)
public static void GetGlobal(int narg, int undefok) throws CallinException
narg
- the number of subscripts in the global reference stackedundefok
- TRUE means that if the global reference is not defined
the operation returns NULL on the stack. FALSE means that an exception
will be thrown.
CallinException
PushGlobal(String)
,
PushGlobal(String,String)
,
PushArg(String)
,
PushArg(int)
,
PushArg(float)
,
PushArg(double)
public static void SetGlobal(int narg) throws CallinException
narg
- the number of subscripts in the global reference stacked
CallinException
PushGlobal(String)
,
PushGlobal(String,String)
,
PushArg(String)
,
PushArg(int)
,
PushArg(float)
,
PushArg(double)
public static void Execute(String cmd) throws CallinException
cmd
- the string to be executed as a COS statement
CallinException
public static void Evaluate(String cmd) throws CallinException
cmd
- the string to be evaluated as a COS expression
CallinException
public static String ErrorMessage(int code) throws CallinException
CacheException.getCode()
. If this method is
passed an unknown error code, a message to that effect is returned
instead of the actual error text.
code
- error code to translate
CallinException
CacheException.getCode()
public static int TopArgType() throws CallinException
CACHE_ERNORES
is returned.
CACHE_TYPE_INT
,
CACHE_TYPE_DOUBLE
, CACHE_TYPE_STRING
,
CACHE_TYPE_OREF
.
CallinException
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |