Native and generated Java™ code
can now share database connections, allowing you to commit database
changes made earlier in a run unit that contains both kinds of code.
To make the capability work, use the following PowerServer Java class and the same-named EGL
external type: SharedResourcePowerServer.
An object of that type allows the native and generated Java programs to share a set of database connections.
The set of connections is determined by two mechanisms:
- In generated Java; for example,
by calls to the SQLLib.connect system function.
- In native Java, by calls
to the addConnection method of the SharedResourcePowerServer.
When you are writing EGL code, you can access a SharedResourcePowerServer
object by invoking JavaLib.getSharedResourcePowerServer.
You might have created connections only in the current EGL program;
but to provide the connection detail, you pass the object to the native Java code. This sharing mechanism
works in whatever way you access the native Java code; whether by way of an external type
or by way of a Java access function
that is provided in the JavaLib system library.
The current topic describes only the following methods of SharedResourcePowerServer:
Those methods are unique to SharedResourcePowerServer and are in
addition to the methods provided by either PowerServer or SharedResourcePowerServer.
For an overview on how to use an object of either type in native Java code, see "Java wrapper classes."
For further detail, see Other considerations.
addConnection
The addConnection
method adds a database connection and makes that connection current
in the programs generated by EGL. If the addConnection method is invoked
repeatedly, a connection that was specified in an earlier call is
still available until that connection is closed.
public void addConnection( Connection con, String name, int disconnectOption )
throws NullPointerException, IllegalArgumentException, JavartException
- con
- A connection to the kind of database that was specified in the
program's DBMS build descriptor option. A connection is of type java.sql.Connection.
- name
- The name that you are assigning to that connection. You use the
name when calling SQLLib.setCurrentDatabase, SQLLib.beginDatabaseTransaction,
SQLLib.defineDatabaseAlias, or SQLLib.disconnect.
- disconnectOption
- One of the following SharedResourcePowerServer class values:
- DISCONNECT_NEVER
- The EGL runtime never closes the connection.
In essence this
value is the default. An overloaded method variation takes only two
parameters, in which case DISCONNECT_NEVER is provided automatically.
- DISCONNECT_AUTOMATIC
- The connection is closed by a call to SQLLib.disconnect, SQLLib.disconnectAll,
SysLib.commit, or SysLib.rollback; or by a call to either of the following
SharedResourcePowerServer methods: commit or rollBack.
- DISCONNECT_CONDITIONAL
- The connection is closed in any of the following ways:
- By a call to SQLLib.disconnect, SQLLib.disconnectAll, or SysLib.rollback.
- By a call to SysLib.commit when the HOLD option is not in effect
for any of the open result sets that were created by the connection.
- By a call to either of the following SharedResourcePowerServer
methods: commit or rollBack.
- DISCONNECT_EXPLICIT
- The connection is closed by a call to SqlLib.disconnect or SqlLib.disconnectAll
or by a call to the SharedResourcePowerServer close method./
The method throws the following exceptions:
- NullPointerException when con or name is
null.
- IllegalArgumentException when name is empty or
all whitespace or when disconnectionOption is invalid.
- JavartException when the connection cannot be used.
getConnection
The getConnection
method returns the named connection, or null if no connection has
the given name.
public Connection getConnection( String name ) throws JavartException
- name
- Name of the connection.
The returned connection is of type java.sql.Connection.
The method throws a JavartException after an internal error.
getConnections
The getConnections
method returns a Map object that relates the names of active connections
to the objects of type java.sql.Connection. You cannot modify the
returned Map object, which is of type java.util.Map.
public Map <String, Connection> getConnections() throws JavartException
The
method throws a JavartException after an internal error.
getCurrentConnection
The
getCurrentConnection method returns the active connection, or null
if a current connection is not in effect.
public Connection getCurrentConnection() throws JavartException
The
returned connection is of type java.sql.Connection. The method throws
a JavartException after an internal error.
releaseConnection
The
releaseConnection method closes the connection object if the connection
is open and if the disconnect option is different from DISCONNECT_NEVER.
Even if the disconnect option is DISCONNECT_NEVER or if the connection
is already closed, the EGL runtime can release resources associated
with the connection.
Two variations of this method are available:
public void releaseConnection( String name ) throws JavartException, SQLException
public void releaseConnection( Connection con ) throws JavartException, SQLException
- name
- Name of the connection.
- con
- The connection object, which is of type java.sql.Connection.
The method throws the following exceptions:
- SQLException when the database management system returns an error.
- JavartException when an internal error occurs.
Other considerations
Several
considerations apply when you work with an object of type SharedResourcePowerServer:
- If you close a connection in your native Java code, release the resources by calling
one of the releaseConnection methods.
- When you are writing your native Java code,
be aware that runtime errors are possible in the following situation:
a connection is in use in your generated Java code; the native Java code either closes the connection or performs
a commit or rollback; and the generated code uses the connection again.
Here is an example:
- The generated code issues a prepare statement;
invokes native Java code either
by way of an external type or by way of a JavaLib access
function; and passes an object that was provided by the JavaLib.getSharedResourcePowerServer function.
- The native code closes the connection and returns control to the
generated code.
- The generated code uses the statement that was created by the
earlier prepare statement; but the generated
code fails because the prepared statement was closed earlier, when
the connection was closed.
- Your EGL logic might assign more than one connection to the SharedResourcePowerServer
object. By default, EGL statements use the last connection passed
to powerServer.addConnection(). You can select a new connection by
invoking SQLLib.setCurrentDatabase.
- Calls to SysLib.commit or SysLib.rollback affect
all connections that were assigned to a SharedResourcePowerServer
object. However, the following situation is possible: the EGL runtime
commits a change made with an initial connection but encounters a
problem and fails when committing a change made with a second connection.
After a failure, your data is left in an inconsistent state because
the commit is a one-phase commit, rather than a two-phase commit such
that all resources are committed or none of them are.
- Generated code can only use a connection in the thread where the
connection was created.