Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## net.jini.space
Interface JavaSpace

public interface JavaSpace

This interface is implemented by servers that export a JavaSpaces(TM) technology service. The operations in this interface are the public methods that all such spaces support.

See Also:
  `Entry`

Field Summary
`static long` | `NO_WAIT` Wait for no time at all.

Method Summary
`EventRegistration` | `notify(Entry tmpl, Transaction txn, RemoteEventListener listener, long lease, MarshalledObject handback)` When entries are written that match this template notify the given `listener` with a `RemoteEvent` that includes the `handback` object.
`Entry` | `read(Entry tmpl, Transaction txn, long timeout)` Read any matching entry from the space, blocking until one exists.
`Entry` | `readIfExists(Entry tmpl, Transaction txn, long timeout)` Read any matching entry from the space, returning `null` if there is currently is none.
`Entry` | `snapshot(Entry e)` The process of serializing an entry for transmission to a JavaSpaces service will be identical if the same entry is used twice.
`Entry` | `take(Entry tmpl, Transaction txn, long timeout)` Take a matching entry from the space, waiting until one exists.
`Entry` | `takeIfExists(Entry tmpl, Transaction txn, long timeout)` Take a matching entry from the space, returning `null` if there is currently is none.
`Lease` | `write(Entry entry, Transaction txn, long lease)` Write a new entry into the space.

Field Detail

### NO_WAIT

    public static final long NO_WAIT

  Wait for no time at all. This is used as a timeout value in various read and take calls.

  See Also:
    `read(net.jini.core.entry.Entry, net.jini.core.transaction.Transaction, long)`, `readIfExists(net.jini.core.entry.Entry, net.jini.core.transaction.Transaction, long)`, `take(net.jini.core.entry.Entry, net.jini.core.transaction.Transaction, long)`, `takeIfExists(net.jini.core.entry.Entry, net.jini.core.transaction.Transaction, long)`, Constant Field Values

Method Detail

### write

    public Lease write(Entry entry,
                       Transaction txn,
                       long lease)
                throws TransactionException,
                       RemoteException

  Write a new entry into the space.

  Parameters:
    `entry` - the entry to write
    `txn` - the transaction object, if any, under which to perform the write
    `lease` - the requested lease time, in milliseconds
  Returns:
    a lease for the entry that was written to the space
  Throws:
    `TransactionException` - if a transaction error occurs
    `RemoteException` - if a communication error occurs

### read

    public Entry read(Entry tmpl,
                      Transaction txn,
                      long timeout)
               throws UnusableEntryException,
                      TransactionException,
                      InterruptedException,
                      RemoteException

  Read any matching entry from the space, blocking until one exists. Return `null` if the timeout expires.

  Parameters:
    `tmpl` - The template used for matching. Matching is done against `tmpl` with `null` fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").
    `txn` - The transaction (if any) under which to work.
    `timeout` - How long the client is willing to wait for a transactionally proper matching entry. A timeout of `NO_WAIT` means to wait no time at all; this is equivalent to a wait of zero.
  Returns:
    a copy of the entry read from the space
  Throws:
    `UnusableEntryException` - if any serialized field of the entry being read cannot be deserialized for any reason
    `TransactionException` - if a transaction error occurs
    `InterruptedException` - if the thread in which the read occurs is interrupted
    `RemoteException` - if a communication error occurs
    `IllegalArgumentException` - if a negative timeout value is used

### readIfExists

    public Entry readIfExists(Entry tmpl,
                              Transaction txn,
                              long timeout)
                       throws UnusableEntryException,
                              TransactionException,
                              InterruptedException,
                              RemoteException

  Read any matching entry from the space, returning `null` if there is currently is none. Matching and timeouts are done as in `read`, except that blocking in this call is done only if necessary to wait for transactional state to settle.

  Parameters:
    `tmpl` - The template used for matching. Matching is done against `tmpl` with `null` fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").
    `txn` - The transaction (if any) under which to work.
    `timeout` - How long the client is willing to wait for a transactionally proper matching entry. A timeout of `NO_WAIT` means to wait no time at all; this is equivalent to a wait of zero.
  Returns:
    a copy of the entry read from the space
  Throws:
    `UnusableEntryException` - if any serialized field of the entry being read cannot be deserialized for any reason
    `TransactionException` - if a transaction error occurs
    `InterruptedException` - if the thread in which the read occurs is interrupted
    `RemoteException` - if a communication error occurs
    `IllegalArgumentException` - if a negative timeout value is used
  See Also:
    `read(net.jini.core.entry.Entry, net.jini.core.transaction.Transaction, long)`

### take

    public Entry take(Entry tmpl,
                      Transaction txn,
                      long timeout)
               throws UnusableEntryException,
                      TransactionException,
                      InterruptedException,
                      RemoteException

  Take a matching entry from the space, waiting until one exists. Matching is and timeout done as for `read`.

  Parameters:
    `tmpl` - The template used for matching. Matching is done against `tmpl` with `null` fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").
    `txn` - The transaction (if any) under which to work.
    `timeout` - How long the client is willing to wait for a transactionally proper matching entry. A timeout of `NO_WAIT` means to wait no time at all; this is equivalent to a wait of zero.
  Returns:
    the entry taken from the space
  Throws:
    `UnusableEntryException` - if any serialized field of the entry being read cannot be deserialized for any reason
    `TransactionException` - if a transaction error occurs
    `InterruptedException` - if the thread in which the take occurs is interrupted
    `RemoteException` - if a communication error occurs
    `IllegalArgumentException` - if a negative timeout value is used
  See Also:
    `read(net.jini.core.entry.Entry, net.jini.core.transaction.Transaction, long)`

### takeIfExists

    public Entry takeIfExists(Entry tmpl,
                              Transaction txn,
                              long timeout)
                       throws UnusableEntryException,
                              TransactionException,
                              InterruptedException,
                              RemoteException

  Take a matching entry from the space, returning `null` if there is currently is none. Matching is and timeout done as for `read`, except that blocking in this call is done only if necessary to wait for transactional state to settle.

  Parameters:
    `tmpl` - The template used for matching. Matching is done against `tmpl` with `null` fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").
    `txn` - The transaction (if any) under which to work.
    `timeout` - How long the client is willing to wait for a transactionally proper matching entry. A timeout of `NO_WAIT` means to wait no time at all; this is equivalent to a wait of zero.
  Returns:
    the entry taken from the space
  Throws:
    `UnusableEntryException` - if any serialized field of the entry being read cannot be deserialized for any reason
    `TransactionException` - if a transaction error occurs
    `InterruptedException` - if the thread in which the take occurs is interrupted
    `RemoteException` - if a communication error occurs
    `IllegalArgumentException` - if a negative timeout value is used
  See Also:
    `read(net.jini.core.entry.Entry, net.jini.core.transaction.Transaction, long)`

### notify

    public EventRegistration notify(Entry tmpl,
                                    Transaction txn,
                                    RemoteEventListener listener,
                                    long lease,
                                    MarshalledObject handback)
                             throws TransactionException,
                                    RemoteException

  When entries are written that match this template notify the given `listener` with a `RemoteEvent` that includes the `handback` object. Matching is done as for `read`.

  Parameters:
    `tmpl` - The template used for matching. Matching is done against `tmpl` with `null` fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").
    `txn` - The transaction (if any) under which to work.
    `listener` - The remote event listener to notify.
    `lease` - the requested lease time, in milliseconds
    `handback` - An object to send to the listener as part of the event notification.
  Returns:
    the event registration to the the registrant
  Throws:
    `TransactionException` - if a transaction error occurs
    `RemoteException` - if a communication error occurs
    `IllegalArgumentException` - if the lease time requested is not Lease.ANY and is negative
  See Also:
    `read(net.jini.core.entry.Entry, net.jini.core.transaction.Transaction, long)`, `EventRegistration`

### snapshot

    public Entry snapshot(Entry e)
                   throws RemoteException

  The process of serializing an entry for transmission to a JavaSpaces service will be identical if the same entry is used twice. This is most likely to be an issue with templates that are used repeatedly to search for entries with `read` or `take`. The client-side implementations of `read` and `take` cannot reasonably avoid this duplicated effort, since they have no efficient way of checking whether the same template is being used without intervening modification. The `snapshot` method gives the JavaSpaces service implementor a way to reduce the impact of repeated use of the same entry. Invoking `snapshot` with an `Entry` will return another `Entry` object that contains a snapshot of the original entry. Using the returned snapshot entry is equivalent to using the unmodified original entry in all operations on the same JavaSpaces service. Modifications to the original entry will not affect the snapshot. You can `snapshot` a `null` template; `snapshot` may or may not return null given a `null` template. The entry returned from `snapshot` will be guaranteed equivalent to the original unmodified object only when used with the space. Using the snapshot with any other JavaSpaces service will generate an `IllegalArgumentException` unless the other space can use it because of knowledge about the JavaSpaces service that generated the snapshot. The snapshot will be a different object from the original, may or may not have the same hash code, and `equals` may or may not return `true` when invoked with the original object, even if the original object is unmodified. A snapshot is guaranteed to work only within the virtual machine in which it was generated. If a snapshot is passed to another virtual machine (for example, in a parameter of an RMI call), using it--even with the same JavaSpaces service--may generate an `IllegalArgumentException`.

  Parameters:
    `e` - the entry to take a snapshot of.
  Returns:
    a snapshot of the entry.
  Throws:
    `RemoteException` - if a communication error occurs

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved