public interface CommunicationLifeCycle
Super-interface common to all lifecycles objects of a given Context
.
The 5 kind of objects (Connection
, Filter
, Query
,
Subscription
and Transaction
) that implement this interface:
makeSomething
methods of their
Context
,
Listener
and
parameter
.
Listener
methods in the Java application.
main
Java thread may safely terminate and the application
continue to run until there are some JFT implementation threads running (see
the
section 12.8 of the Java Language Specification).
There is at least one JFT implementation thread:
Listener
methods eligible to be called (e.g.
a Connection.STATUS_CONNECTING
, or a
Subscription.STATUS_STARTED
, or a Query.STATUS_DESTROYING
,
or ...) because there are some i/o data pending.
LifeCycle.STATUS_RELEASED
so a sure manner to terminate a Java
application that use JFT is: JFT.THIS
.release()
This is always guaranteed, even inside the Listener
methods
called inside the JFT implementation threads. So the programmer that uses the
JFT library is free to synchronize on these objects for his needs.
But Warning:
Each Listener method must execute its task within the shortest time possible.
Do not synchronize anything or make time-intensive computation inside the Listener methods because this may deadlock the JFT library.
If you have an impelling necessity to do so, you have to start another thread to accomplish your needs.
So, please, do not download a file from FTP and/or do not compute the first one million digits of PI inside a Listener method!
In addition there is no need to synchronize any activity between the
programmer and the JFT library. All needed synchronizations are made by JFT
library on internal hidden objects, not accessible to the JFT programmer that
use this JFT API.
E.g. for internal needs the JFT implementation may synchronize their
implementation threads on the subscriptions or on the connections: this is
made synchronizing on the private hidden fields lockObject that are
present in the JFT implementation of Subscription and Connection.
The primitive data returned by the implementation to the JFT application
(e.g. the status returned by LifeCycle.getStatus()
method) are
internally implemented as primitive volatile
data, so they are
almost always in synch between the implementation and the application.
So the JFT application does not need to protect itself with something like:
if (mySubscription.getStatus() == LyfeCycle.STATUS_INIT)
mySubscription.start();
because, even if the status returned in
mySubscription.getStatus()
is
LyfeCycle.STATUS_INIT
, when the application invoke the
mySubscription.start()
method, the status may already be
changed to STATUS_RELEASED
because another thread, in the
meantime, has released the Connection associated to
mySubscription
.
The JFT library implementation instead surely synchronize the access to the
various objects and status with something like:
public int start() {
synchronized(lockObject) {
if (status == STATUS_INIT) {
...
status = STATUS_STARTING;
}
}
}
E.g. this prevents any status changes by others threads inside the
start()
code.
but
LifeCycle
Field Summary |
---|
Fields inherited from interface LifeCycle |
---|
RESULT_GENERIC_ERROR, RESULT_INVALID_STATUS, RESULT_OK, STATUS_INIT, STATUS_RELEASED |
Method Summary | |
---|---|
Context |
getContext()
Returns the associated Context. |
Listener |
getListener()
Returns the associated Listener. |
Param |
getParam()
Returns the associated Param. |
Methods inherited from interface LifeCycle |
---|
enumChilds, getStatus, release |
Method Detail |
---|
Context getContext()
Each CommunicationLifeCycle object has a Context from which it was
created (e.g. for a Subscription
the associated Context is the
object on which the
Context.makeSubscription()
method was
invoked).
This method return this Context.
null
is never returned.Param getParam()
Each CommunicationLifeCycle object has a specialized sub-interface of
Param that described the specific creation parameter for that object
(e.g. for a Subscription
the associated Param is the second
parameter (SubscriptionParam
) of
Context.makeSubscription()
).
This method return this parameter casted to the super-interface
Param
.
All parameters returned by this method are bound
.
null
is never returned.Listener getListener()
Each CommunicationLifeCycle object has a specialized sub-interface of
Listener that described the specific listener for that object (e.g. for a
Subscription
the associated Listener is the Third parameter (SubscriptionListener
)
of Context.makeSubscription()
).
This method return this parameter casted to the super-interface
Listener
.
null
is never returned.