com.ccg.values
Interface ValuesHolder

All Known Subinterfaces:

ValuesConfig, ValuesEditor

All Known Implementing Classes:

TimeSpanEditor, ValuesConfigBean, ValuesEditorAdapter, ValuesEditorBean, ValuesPropertiesAdapter

public interface ValuesHolder

Definition of objects which are capable of holding values (settings) for other objects.

This interface attempts to define the minimal functionality in for implementations which are designed to work with the values of a particular class of objects. In particular, a ValuesHolder can:

• Set the values it holds to a instance of a object which it is designed to work with.
• Get values from a instance of a object which it is designed to work with.
• Can let you know the class of objects which they were designed for and what its capabilities are.

Here is a simple UML Class diagram:

For example, consider the TimeSpan object. One might want to design a Swing component which can load the values from the TimeSpan object, let the user edit the values, and then store them back into the TimeSpan object. Another example, could involve a properties file, where the values for the TimeSpan object are stored as properties and the implementation of the ValuesHolder is responsible for transferring the values between the object and the associated property file.

Here are the contractual rules for those that implement this interface:

getObjectClass

This method must return a non-null value which indicates the class/interface which the ValuesHolder was created for.

getCapabilities

This method must return a set of bit flags indicating whether the toObject and/or fromObject methods are supported. Most implementation will simply return the constant ValuesHolder.HAS_TO_FROM.

toObject

This attempts to transfer the values held into the object passed. It MUST throw a IllegalArgumentException if the incorrect type of argument is passed. It may throw a IllegalStateException if the "holder" is not in a valid state to transfer information to the object. It may also throw a UnsupportedOperationException if it isn't capable of this operation.

fromObject

This attempts to transfer information from the object passed into the "value holder". It MUST throw a IllegalArgumentException if the incorrect type of argument is passed. It may throw a IllegalStateException if the object passed is not in the proper state to allow for the transfer. It may also throw a UnsupportedOperationException if it isn't capable of this operation.

Avoid Partial Transfers

A correct implementation will not permit partial transfers. If an exception is thrown by either the to/from methods, then NO information should be transferred. These methods should be thought of as "all or nothing".

Optional to/from Implementation

Whether or not both the toObject and fromObject are implemented is implementation dependent. There are cases where only one is reasonably implemented. For example, a ValuesHolder implementation which uses parameters from HTTP POST would only be able to implement the toObject method (as it can only transfer values from the POST to the object and not the other way). Where as a ValuesHolder that simply printed the values of object to piece of paper would only be able to implement the fromObject side (its hard to get the information back from the sheet of paper). It is strongly encouraged that BOTH the fromObject and toObject methods are implemented. In either case, the implementation of the getCapabilities method MUST properly indicate what methods are supported.

Since:

1.0

Version:

$Revision: 1.2 $

Author:

$Author: pkb $

See Also:

ValuesEditor, ValuesConfig

Field Summary

static int	HAS_FROM Bit flag indicating that the ValuesHolder supports the fromObject method.
static int	HAS_TO Bit flag indicating that the ValuesHolder supports the toObject method.
static int	HAS_TO_FROM Bit flag indicating that the ValuesHolder supports both the fromObject and toObject methods.

Method Summary

void	fromObject(Object o) Transfer values from a object into this "value holder".
int	getCapabilities() Determine what the ValuesHolder implementation supports.
Class	getObjectClass() Get the Class which the "values holder" is designed to work with.
void	toObject(Object o) Transfer values from this "value holder" into a object.

Field Detail

HAS_TO

static final int HAS_TO

Bit flag indicating that the ValuesHolder supports the toObject method.

The following demonstrates how one can use this bit flag to determine if a ValuesHolder implementation supports the toObject method.

 static boolean hasTo(ValuesHolder vh) {
   int vcap = vh.getCapabilities();
   return ((vcap & ValuesHolder.HAS_TO) == ValuesHolder.HAS_TO);
 }
 

Since:

1.0

See Also:

Constant Field Values

HAS_FROM

static final int HAS_FROM

Bit flag indicating that the ValuesHolder supports the fromObject method.

The following demonstrates how one can use this bit flag to determine if a ValuesHolder implementation supports the fromObject method.

 static boolean hasFrom(ValuesHolder vh) {
   int vcap = vh.getCapabilities();
   return ((vcap & ValuesHolder.HAS_FROM) == ValuesHolder.HAS_FROM);
 }
 

Since:

1.0

See Also:

Constant Field Values

HAS_TO_FROM

static final int HAS_TO_FROM

Bit flag indicating that the ValuesHolder supports both the fromObject and toObject methods.

The following demonstrates how one can use these bit flags to determine if a ValuesHolder implementation supports both the fromObject AND toObject methods.

 static boolean hasToFrom(ValuesHolder vh) {
   int vcap = vh.getCapabilities();
   return ((vcap & ValuesHolder.HAS_TO_FROM) == ValuesHolder.HAS_TO_FROM);
 }
 

Since:

1.0

See Also:

Constant Field Values

Method Detail

getCapabilities

int getCapabilities()

Determine what the ValuesHolder implementation supports.

This method allows one to determine what is supported by the ValuesHolder implementation. If this method indicates that the implementation supports the toObject method (the HAS_TO bit is set, then the toObject method should NEVER throw the UnsupportedOperationException. Likewise, if this method indicates that the implementation supports the fromObject method (the HAS_FROM bit is set, then the fromObject method should NEVER throw the UnsupportedOperationException.

A full (bi-directional) implementation (which is encouraged and the most useful) will return a value that has both the HAS_FROM and the HAS_TO bits set (HAS_TO_FROM).

Returns:

A set of bit flags indicating what is supported by the implementation.

Since:

1.0

See Also:

HAS_TO_FROM

getObjectClass

Class getObjectClass()

Get the Class which the "values holder" is designed to work with.

This method returns the Class which the "values holder" is designed to work with. All objects which are passed to the toObject or fromObject methods MUST be instances of this class.

Returns:

The class this "values holder" is designed to work with - never returns null.

Since:

1.0

toObject

void toObject(Object o)
              throws IllegalStateException,
                     IllegalArgumentException,
                     UnsupportedOperationException,
                     NullPointerException

Transfer values from this "value holder" into a object.

This method transfers all of the values held into the object passed. It transfers ALL values if successful. It transfers ZERO values if a exception is thrown.

Throws:

NullPointerException - If you pass null.

IllegalArgumentException - If the object passed is not the proper type.

IllegalStateException - If the "values holder" isn't in the proper state to do the transfer.

UnsupportedOperationException - If the "value holder" doesn't implement the setting of values in the associated objects.

Since:

1.0

See Also:

fromObject(java.lang.Object)

fromObject

void fromObject(Object o)
                throws IllegalStateException,
                       IllegalArgumentException,
                       UnsupportedOperationException,
                       NullPointerException

Transfer values from a object into this "value holder".

This method transfers all of the values of interest from the object passed into this "value holder". It transfers ALL values if successful. It transfers ZERO values if a exception is thrown.

Throws:

NullPointerException - If you pass null.

IllegalArgumentException - If the object passed is not the proper type.

IllegalStateException - If the object isn't in the proper state to do the transfer into this "values holder".

UnsupportedOperationException - If the "value holder" doesn't implement the getting of values from associated objects.

Since:

1.0

See Also:

toObject(java.lang.Object)