SharedResourcePowerServer

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:

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:
    1. 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.
    2. The native code closes the connection and returns control to the generated code.
    3. 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.

Feedback