com.sun.jini
software, its API documentation,
release notes for those classes and interfaces, examples, and
references to the specific copyrights and licenses that protect each of
the aforementioned components.
This document contains release notes for the Jini Software Kit API documentation, future directions that this software could take, and specifics on these packages:
If you have comments on the JSK, you can send email to jini-comments@java.sun.com. If you would like to submit a bug against the JSK, please send it to jini-submit@java.sun.com. If you encounter problems that you would like help with, you can subscribe to the jini-users list by sending email to listserv@java.sun.com, with a message of "subscribe jini-users".
You may notice that the on-line API documentation (javadoc) was not
produced for every class and interface in the com.sun.jini
packages. This omission was intentional; we did not produce on-line API
documentation for classes that were very implementation specific. We
only produced on-line API documentation for the classes and interfaces
that should be important to you, or that you may find useful. However,
our implementation-specific classes and interfaces have javadoc
comments, so that if you wish, you can produce the API docs yourself.
Please let us know how you feel about this documentation approach by
sending email to jini-comments@java.sun.com, with a subject of "API
documentation".
The
com.sun.jini
package and its sub-packages contain our
implementation of various Jini services. At present, all classes and
interfaces in these packages are subject to change or removal in a
future release, in ways that may not be backward compatible with this
release.
We realize that there are administrative interfaces that you will need to depend on to effectively use Jini technology, and common tasks that Jini services and applications will have to perform that can be abstracted into utility classes. The following packages contain code specifically related to Jini technology that we invite you to review and provide feedback:
com.sun.jini.admin com.sun.jini.discovery com.sun.jini.lease com.sun.jini.lease.landlord com.sun.jini.lookup com.sun.jini.lookup.entry
The classes that we believe have the broadest utility are:
com.sun.jini.admin.DestroyAdmin com.sun.jini.lease.AbstractLease com.sun.jini.lease.AbstractLeaseMap com.sun.jini.lease.LeaseRenewalManager com.sun.jini.lookup.JoinManager com.sun.jini.lookup.entry.BasicServiceType
If you find a class, interface, or method that is particularly useful and you would like to see it included or enhanced in future releases, please send your suggestions to jini-comments@java.sun.com.
A general utility, com.sun.jini.lease.LeaseRenewalManager
,
has been provided to make it easy to renew leases.
It is strongly recommended that services in the Jini system use the
general utility class, com.sun.jini.lookup.JoinManager
, to
participate in the Jini Discovery and Join protocols. This class
encapsulates the proper behavior of a service that wishes to be a good
"citizen" of the Jini Lookup service.
From the command-line, the syntax for starting up the lookup service would look like:
java -jar executable_jar_file
codebase_arg lookup_policy_file_arg log_directory_arg
Where:
-jar
is an option to the java
command that
tells the interpreter to execute a program in the jar file provided as an
argument.
executable_jar_file
is the jar file that contains a
program that is identified by the manifest as having a
main
method. In this case, this argument would be the
absolute path to the reggie.jar
file, which has the
com.sun.jini.reggie.CreateLookup
class identified as the
Main-Class. For more information on the -jar
option
of java
take a look at:
http://java.sun.com/products/jdk/1.2/docs/tooldocs/solaris/java.html http://java.sun.com/products/jdk/1.2/docs/tooldocs/win32/java.html http://java.sun.com/products/jdk/1.2/docs/guide/jar/manifest.html http://java.sun.com/products/jdk/1.2/docs/tooldocs/solaris/jar.html http://java.sun.com/products/jdk/1.2/docs/tooldocs/win32/jar.html
codebase_arg
is the first argument passed to the
main
method of CreateLookup
. This argument is used to
specify the URL of the reggie-dl.jar
that will be downloaded
to lookup service clients.
lookup_policy_file_arg
is the second argument to the
main
method of CreateLookup
. This argument
is used to specify the security policy file that should be passed to
the activation group descriptor
(java.rmi.activation.ActivationGroupDesc
) for the lookup
service.
log_directory_arg
is the third argument to the
main
method of CreateLookup
. This argument is used to
specify the log directory that the lookup service should use.
For example:
java -jar /files/jini1_0/lib/reggie.jar http://`hostname`:8080/reggie-dl.jar
/files/jini1_0/example/lookup/policy /tmp/reggie_log
The following system properties control the behavior of Sun's implementation of the Jini Lookup service:
net.jini.discovery.announce
com.sun.jini.reggie.unicastTimeout
The current implementation of Reggie participates in the Jini
Discovery and Join protocols using the LookupDiscovery
class. The operation of this class can be controlled by the system
properties described in the JXP release notes.
java.lang.NoSuchMethodError: stub class initialization failed
net.jini.discovery.LookupDiscovery$UnicastDiscoverer.run(Compiled Code)
UnknownHostException
errors may occur in the RMI subsystem.
These spurious errors are due to network timeouts. These errors cause the RMI subsystem to enable its multiplexed mode of operation; producing the following warning on the console (System.out
):
Note that the above condition does not
result in system failure; only a slight degradation in performance.
To work around this problem, do the following:
Start/Settings/Control Panel
Control Panel
, double click
on the icon labeled Network
com.sun.jini.reggie.proxy.debug
property was added.
See the property description above for more detail.
Mahalo was designed to run as a service within a Jini system or
standalone. For this reason, Mahalo includes classes necessary for
running in the Jini system environment. General information on the
Jini technology may be found in the Jini technology release notes.
Jar File Structure
To facilitate code downloading to clients, the Mahalo implementation is separated into two jar files.
- mahalo.jar
This file contains all of the class files needed byTxnManagerImpl
in order to run. This file has been configured as an "executable jar." When used with the-jar
command-line option in the Java TM VM, it will start up a transaction manager.
- mahalo-dl.jar
This file contains all of the class files needed by clients to interact with the transaction manager server. Thejava.rmi.server.codebase
property of a Mahalo service must be a URL which points to themahalo-dl.jar
file. If the codebase property has been properly set, themahalo-dl.jar
file does not have to be a part of the client's classpath since the code will be downloaded from the URL specified in the codebase. This allows client programs to be deployed independently from any particular transaction manager implementation. Note: A URL may refer to a remote machine, local machine, or local filesystem.Features
- Mahalo is implemented using RMI object activation. As a result, once Mahalo has been properly set up, it does not actually run until clients use references to it.
- Mahalo performs logging. If Mahalo's process should exit, the logging information is consulted to rebuild Mahalo's state as part of recovery.
- Mahalo is implemented using a thread-pool model, so that committed and aborted transactions are handled efficiently.
- Mahalo's transactions are leased resources and are reclaimed if clients do not explicitly renew.
- Using a flexible mechanism, a reference to Mahalo may be bound to a Jini Lookup service or to an RMI registry.
- When used with a Jini Lookup service, attributes associated with an instance of Mahalo may be defined and modified.
- Mahalo uses jar files for the Java platform and code downloading, so that thin clients may interact with Mahalo without requiring any prior installation.
- Mahalo uses JDK1.2 security. Users must define permissions for Mahalo in a security policy file.
- Mahalo is a Java application and may run on a compliant JavaTM virtual machine (JVM).
- When settling transactions, Mahalo begins the attempt aggressively and backs off after successive failed attempts.
Mahalo Limitations
- The current release of Mahalo does not support nested transactions.
- The current release of Mahalo supports limited administration interfaces.
- Transactions are assumed to be short lived. If there are many outstanding unsettled transactions (in a COMMITTED or ABORTED state), depending on the tuning parameters chosen for your underlying operating system, a filesystem limit may potentially be reached.
com.sun.jini.use.registry
com.sun.jini.use.registry
property is set to a
non-null value, the service will bind itself into the RMI registry.
This property must be set on the VM that is creating the service. It
is only used when creating a service from the command line. This
property has no effect on how the service binds itself into Jini Lookup
servers.
Note: Currently Mahalo can be configured to bind itself into an RMI registry or a Jini Lookup service. Support for binding into an RMI registry is being provided so developers can incorporate Jini technology into their systems incrementally instead of all at once. It is quite likely that we will remove support for binding into an RMI registry in future versions of Mahalo.
com.sun.jini.rmiRegistryPort
com.sun.jini.mahalo.managerName
com.sun.jini.mahalo.managerName
property defines
the name associated with the transaction manager. If the transaction
manager is bound to the RMI registry, then the value of the
managerName
property is the name to which it is bound. If
the transaction manager is bound to the Jini Lookup service, this name
is used to create an attribute of type
net.jini.lookup.entry.Name
which is associated with the
transaction manager's ServiceItem
. This property must be
set on the VM that is creating the service. It is only used when
creating a Mahalo service from the command line.
java.security.policy
java.security.policy
property
defines the path to the security policy file for the program that sets
up the transaction manager. The security policy for transaction
manager's VM should be specified by the second command-line argument to
Mahalo.
java.rmi.server.codebase
java.rmi.server.codebase
property determines the URL that clients will use to load the classes
of objects they get from the transaction manager. This URL is set by
the first required command-line argument.
getState
on a ServerTransaction
created by a Mahalo server may report erroneous results.
Calling getState
on a ServerTransaction
shortly after its lease has expired may return the transaction's last
state instead of returning a value of "aborted" or throwing an
UnknownTransactionException
. Future calls to
getState
after an appropriate delay will provide a correct
result. Most users of getState
are unlikely to need
additional code to compensate for this bug since they are likely to be
making periodic calls to getState
.
When destroying a Mahalo server using the destroy
method
of its administration interface the Mahalo server does not always
remove all of its persistent state from the file system. This is
usually only a problem when running on Windows operating systems. The
workaround is to remove the log directory and any extra files after the
service has terminated using tools provided by the operating system.
The changes are as follows:
TransactionManager
logs aborted transactions, the
list of participants joined in the transactions are included in the
logging information. This allows the manager to contact participants
appropriately when an aborted transaction has been recovered after the
manager was restarted.
TimeoutExpiredException
, and interacting with
participants.
TimeoutExpiredException
.
Inside the exception is a boolean flag representing whether or not
the transaction was successful in its attempt to commit or abort.
TransactionManager
is started, unsettled transactions
recovered from the logs are now asynchronously forced to completion.
The startup time is reduced as a result, because the transaction manager no
longer waits for all recovered transactions to settle as a prerequisite
of the startup process. This means that the transaction manager can
accept and service new client requests sooner.
prepareAndCommit
optimization was added so that if a
single participant is joined in a transaction, the manager calls the
participant's prepareAndCommit
method. This causes the
participant to evaluate the result of its "prepare" before returning to
the transaction manager. If the participant has voted PREPARED, it
goes ahead and rolls forward its state before returning to the
transaction manager. Using this optimization, a single message for the
prepareAndCommit
goes across the network from the manager
to the participant instead of two messages for the "prepare" and the
"roll" separately.