org.ws4d.java.communication
Interface Bindable

All Known Subinterfaces:

EventSink, LocalDevice, LocalService

All Known Implementing Classes:

DefaultDevice, DefaultEventSink, DefaultService

public interface Bindable

This interface supports usage and management of communication bindings.

By implementing the Bindable interface, a class indicates that it is capable of being "bound" to one or more communication endpoint addresses (as represented by instances of the CommunicationBinding interface). The methods defined herein allow a client to observe and manipulate these bindings.

Note that some implementations may not support alterations to their communication bindings, or support them solely when it is in certain state(s). The method supportsBindingChanges() is used in order to indicate this. Clients are advised to inspect its return value prior to calling mutator methods like addBinding(CommunicationBinding), removeBinding(CommunicationBinding) or clearBindings().

Example:

 Bindable bindable = ...;
 CommunicationBinding binding = ...;
 if (bindable.supportsBindingChanges()) {
     bindable.add(binding);
 }
 

See Also:

CommunicationBinding

Method Summary

void	addBinding(CommunicationBinding binding) Adds the given binding to this Bindable.
void	clearBindings() Removes all bindings from this Bindable instance.
Iterator	getBindings() Returns an iterator over all bindings assigned to this Bindable instance.
boolean	hasBindings() Returns true only if this Bindable instance has at least one binding assigned.
boolean	removeBinding(CommunicationBinding binding) Removes the specified binding from this Bindable instance.
boolean	supportsBindingChanges() Returns true, if it is safe to call one of the mutator methods ((addBinding(CommunicationBinding), removeBinding(CommunicationBinding), (clearBindings(), etc.) at this time without getting an IllegalStateException.

Method Detail

getBindings

Iterator getBindings()

Returns an iterator over all bindings assigned to this Bindable instance. This iterator will have no next elements (rather than being ), if the Bindable doesn't have any bindings.

Returns:

an iterator over all available bindings

hasBindings

boolean hasBindings()

Returns true only if this Bindable instance has at least one binding assigned. Returns false, if it doesn't have any bindings.

Returns:

whether there are any bindings assigned to that Bindable instance or not

supportsBindingChanges

boolean supportsBindingChanges()

Returns true, if it is safe to call one of the mutator methods ((addBinding(CommunicationBinding), removeBinding(CommunicationBinding), (clearBindings(), etc.) at this time without getting an IllegalStateException. Returns false otherwise.

Some implementations of this interface may not allow for bindings to be added or removed all the time, but rather only when the actual implementation is in a certain set of states (note that this set could be empty or contain solely a single set). By calling this method and observing its return value it is possible for a client to determine whether this Bindable supports changes within its current state.

Returns:

true if this Bindable instance may be modified at the moment without throwing IllegalStateExceptions, false otherwise

See Also:

addBinding(CommunicationBinding), removeBinding(CommunicationBinding), clearBindings()

addBinding

void addBinding(CommunicationBinding binding)
                throws WS4DIllegalStateException

Adds the given binding to this Bindable. Does nothing if the Bindable already contains the binding.

Parameters:

binding - the binding to add

Throws:

WS4DIllegalStateException - in case this Bindable doesn't currently support modifications (see supportsBindingChanges())

removeBinding

boolean removeBinding(CommunicationBinding binding)
                      throws WS4DIllegalStateException

Removes the specified binding from this Bindable instance. Does nothing, if the Bindable doesn't contain the given binding. Returns true if the binding was removed and false if it didn't exist.

Parameters:

binding - the binding to remove

Returns:

true if this Bindable instance had the given binding assigned and it was removed successfully, false otherwise

Throws:

WS4DIllegalStateException - in case this Bindable doesn't currently support modifications (see supportsBindingChanges())

clearBindings

void clearBindings()
                   throws WS4DIllegalStateException

Removes all bindings from this Bindable instance. Does nothing if there are no bindings assigned.

Throws:

WS4DIllegalStateException - in case this Bindable doesn't support modifications at the current time (see supportsBindingChanges())