com.ccg.values.stock
Class TimeSpanEditor

java.lang.Object
  com.ccg.values.ValuesEditorAdapter
      com.ccg.values.stock.TimeSpanEditor

All Implemented Interfaces:

ValuesEditor, ValuesHolder

public class TimeSpanEditor
extends ValuesEditorAdapter

A implementation of a ValuesEditor object suitable for working with time spans.

This class was initially developed as the test implementation of the ValuesEditor interface. However, it is useful for those that wish to create a time span entry field when building GUI interfaces. It allows one to customize the following:

• The format used to display the times in.
• The valid range which times must fall within.
• The labels, tooltips, etc used when constructing the GUI component.

Since:

1.0

Version:

$Revision: 1.3 $

Author:

$Author: pkb $

Field Summary

Fields inherited from interface com.ccg.values.ValuesHolder

HAS_FROM, HAS_TO, HAS_TO_FROM

Constructor Summary

TimeSpanEditor()

Method Summary

Object	createObjectInstance() Creates a new instance of a object (with default values set) which the editor is designed to work with.
void	fromObject(Object o) Transfer values from a object into this "value holder".
JComponent	getComponent() Get the Swing component which the user sees.
(package private) Date	getDateFromString(String s)
Class	getObjectClass() Get the Class which the "values holder" is designed to work with.
void	init(Lookup props) Set the properties to be used when constructing the visual component.
void	toObject(Object o) Transfer values from this "value holder" into a object.
void	validate() Verify that all of the user input fields are valid.

Methods inherited from class com.ccg.values.ValuesEditorAdapter

addChangeListener, checkArgument, fireChangeEvent, getCapabilities, getProxyChangeListener, getProxyDocumentListener, getProxyInputMethodListener, getProxyItemListener, getProxyListDataListener, getProxyTableModelListener, removeChangeListener

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TimeSpanEditor

public TimeSpanEditor()

Method Detail

getObjectClass

public 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

createObjectInstance

public Object createObjectInstance()

Creates a new instance of a object (with default values set) which the editor is designed to work with.

This default implementation returns a short duration (less than two hours) from the current time.

Specified by:

createObjectInstance in interface ValuesEditor

Overrides:

createObjectInstance in class ValuesEditorAdapter

Returns:

Newly allocated and initialized object (should be suitable for either the fromObject or toObject implementation.

Since:

1.0

init

public void init(Lookup props)

Set the properties to be used when constructing the visual component.

This method allows one to customize MANY of the attributes of the graphical component generated based upon the values in the properties passed.

The following affect the display and interpretation of the date/time strings the user edits:

format.template=yyyy-MMM-dd HH:mm:ss.SSS

This option allows one to specify the date format via a "template". See the SimpleDateFormat documentation for full details on how to form the template string. If this value is set, then the "date"/"time" keys are ignored.

format.date=short|medium|long|full

This option allows one to indicate how much date information is required in the format. The valid values correspond to the SHORT, MEDIUM, LONG, and FULL constants defined in the DateFormat class. This setting is ignored if the template=TEXT setting is present. If this setting is omitted, or incorrectly set, then date information is omitted from the output format.

format.time=short|medium|long|full

This option allows one to indicate how much time information is required in the format. The valid values correspond to the SHORT, MEDIUM, LONG, and FULL constants defined in the DateFormat class. This setting is ignored if the template=TEXT setting is present. If this setting is omitted, or incorrectly set, then time information is omitted from the output format.

format.tz=NAME

You can specify a time zone if you don't want the system default (typically omitted).

format.lenient=true|false

You can set this value to true if you want strict parsing rules (if you'll be using the format object to parse input strings). If false, omitted or invalid, then lenient rules will be enforced.

You can use the following to limit the range of dates/times which the user can specify (if omitted - no limits are put in place):

limit.start=INIT_VALUE

This is the minimum (starting) limit for the valid range of times the user may specify. Please note, it MUST be in the proper date format (which you can specify with the format.template option), OR it must be a single integer value representing a millisecond count as used by Java. If omitted, then there will be no limit on the start time.

limit.end=INIT_VALUE

This is the minimum (starting) limit for the valid range of times the user may specify. Please note, it MUST be in the proper date format (which you can specify with the format.template option), OR it must be a single integer value representing a millisecond count as used by Java. If omitted, then no end time limit will be put into affect.

In addition, you may specify any of the following to adjust the start/end time defaults (change TAG to either start or end for the property you would like to adjust):

TAG.name=TEXT

This is the generic name for the component which the application might want access to find the component. This information is not shown to the user (it provides a way to allow the application to locate a GUI component). This is optional.

TAG.label=TEXT

This is the label to appear next to the component.

TAG.value=INIT_VALUE

This is the initial value for the object. Please note, it MUST be in the proper date format (which you can specify with the format.template option), OR it must be a single integer value representing a millisecond count as used by Java.

TAG.background=COLOR

The background color for the component.

TAG.foreground=COLOR

The foreground color for the component.

TAG.font=FONT

The font to use for the component

TAG.tooltip=TEXT

The tool tip to be associated with the component.

TAG.enabled=true|false

Whether the component should be enabled or disable initially (if omitted, we default to true - to create a enabled button).

Specified by:

init in interface ValuesEditor

Overrides:

init in class ValuesEditorAdapter

Parameters:

props - Set of properties (implementation dependent) to initialize object with (must not be null).

Since:

1.0

toObject

public 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.

Parameters:

o - The TimeSpan object to pass information into.

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

public 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.

Parameters:

o - The TimeSpan object to get values from.

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)

validate

public void validate()
              throws IllegalStateException

Verify that all of the user input fields are valid.

This method checks the state of values within the editor. It returns cleanly if everything looks good.

Throws:

IllegalStateException - If any of the user input fields have invalid values contained which the user needs to fix prior to a commit.

Since:

1.0

See Also:

toObject(java.lang.Object)

getComponent

public JComponent getComponent()
                        throws IllegalStateException

Get the Swing component which the user sees.

All classes which implement this interface need to be able to create a GUI editor. This method will return null if the object is unable to comply with the request at this time.

The first invocation triggers the "creation" of the graphical component.

Multiple invocations will return a reference to the same component.

Returns:

A graphical editor for the object - never returns null.

Throws:

IllegalStateException - If the object was not properly initialized.

Since:

1.0

getDateFromString

Date getDateFromString(String s)