jmri.jmrix
Class AbstractThrottleManager

java.lang.Object
  jmri.jmrix.AbstractThrottleManager

All Implemented Interfaces:

ThrottleManager

Direct Known Subclasses:

CbusThrottleManager, DebugThrottleManager, EasyDccThrottleManager, EcosDccThrottleManager, LnPr2ThrottleManager, LnThrottleManager, NceThrottleManager, SerialThrottleManager, SprogCSThrottleManager, SprogThrottleManager, SRCPThrottleManager, ThrottleManager, XNetThrottleManager, XpaThrottleManager

public abstract class AbstractThrottleManager
extends Object
implements ThrottleManager

Abstract implementation of a ThrottleManager.

Based on Glen Oberhauser's original LnThrottleManager implementation.

Author:

Bob Jacobsen Copyright (C) 2001

Nested Class Summary

protected static class

AbstractThrottleManager.Addresses This subClass, keeps track of which loco address have been requested and by whom, it primarily uses a increment count to keep track of all the the Addresses in use as not all external code will have been refactored over to use the new disposeThrottle.

Constructor Summary

AbstractThrottleManager()

Method Summary

protected boolean	addressReleased(DccLocoAddress la, ThrottleListener l)
boolean	addressStillRequired(DccLocoAddress la)
void	attachListener(DccLocoAddress la, PropertyChangeListener p) Attach a PropertyChangeListener to a specific loco address, where the requesting code does not need or require control over the loco.
void	cancelThrottleRequest(int address, boolean isLong, ThrottleListener l) Cancel a request for a throttle
void	cancelThrottleRequest(int address, ThrottleListener l) Cancel a request for a throttle.
void	dispatchThrottle(DccThrottle t, ThrottleListener l) The throttle listener has finished with the specific Throttle and is is available for reuse/reallocation by somebody else.
boolean	disposeThrottle(DccThrottle t, ThrottleListener l) Not for general use, see releaseThrottle and dispatchThrottle.
void	failedThrottleRequest(DccLocoAddress address, String reason) If the system-specific ThrottleManager has been unable to create the DCC throttle then it needs to be removed from the throttleListeners, otherwise any subsequent request for that address results in the address being reported as already in use, if singleUse is set.
Object	getThrottleInfo(DccLocoAddress la, String item) Provides a Proxy method to return the SpeedSetting, Direction, Function Settings, of a throttle, where the requesting code has used the attachListener to only be notified of changes in the throttle and not control it.
boolean	hasDispatchFunction() Check to see if the Dispatch Button should be enabled or not Default to true, override if necessary
void	notifyThrottleKnown(DccThrottle throttle, LocoAddress addr) Handle throttle information when it's finally available, e.g. when a new Throttle object has been created.
void	releaseThrottle(DccThrottle t, ThrottleListener l) The specified Throttle Listener has finished using a given throttle and no longer requires access to it.
void	removeListener(DccLocoAddress la, PropertyChangeListener p) Remove a PropertyChangeListener to a specific loco address, where the requesting code has used attachListener to get notification of changes in a throttle.
boolean	requestThrottle(DccLocoAddress la, ThrottleListener l) Request a throttle, given a decoder address.
boolean	requestThrottle(int address, boolean isLongAddress, ThrottleListener l) Request a throttle, given a decoder address & whether it is a long or short DCC address.
boolean	requestThrottle(int address, ThrottleListener l) Request a throttle, given a decoder address.
void	requestThrottleSetup(LocoAddress a) Abstract member to actually do the work of configuring a new throttle, usually via interaction with the DCC system
abstract void	requestThrottleSetup(LocoAddress a, boolean control) Abstract member to actually do the work of configuring a new throttle, usually via interaction with the DCC system
protected boolean	singleUse() Does this DCC system allow a Throttle (e.g. an address) to be used by only one user at a time?
int	supportedSpeedModes() What speed modes are supported by this system?

Methods inherited from class java.lang.Object

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

Methods inherited from interface jmri.ThrottleManager

addressTypeUnique, canBeLongAddress, canBeShortAddress

Constructor Detail

AbstractThrottleManager

public AbstractThrottleManager()

Method Detail

singleUse

protected boolean singleUse()

Does this DCC system allow a Throttle (e.g. an address) to be used by only one user at a time?

requestThrottle

public boolean requestThrottle(int address,
                               boolean isLongAddress,
                               ThrottleListener l)

Description copied from interface: ThrottleManager

Request a throttle, given a decoder address & whether it is a long or short DCC address. When the decoder address is located, the ThrottleListener gets a callback via the ThrottleListener.notifyThrottleFound method.

Specified by:

requestThrottle in interface ThrottleManager

Parameters:

address - The decoder address desired.

isLongAddress - True if this is a request for a DCC long (extended) address.

l - The ThrottleListener awaiting notification of a found throttle.

Returns:

True if the request will continue, false if the request will not be made. False may be returned if a the throttle is already in use.

requestThrottle

public boolean requestThrottle(DccLocoAddress la,
                               ThrottleListener l)

Request a throttle, given a decoder address. When the decoder address is located, the ThrottleListener gets a callback via the ThrottleListener.notifyThrottleFound method.

Specified by:

requestThrottle in interface ThrottleManager

Parameters:

la - DccLocoAddress of the decoder desired.

l - The ThrottleListener awaiting notification of a found throttle.

Returns:

True if the request will continue, false if the request will not be made. False may be returned if a the throttle is already in use.

requestThrottle

public boolean requestThrottle(int address,
                               ThrottleListener l)

Request a throttle, given a decoder address. When the decoder address is located, the ThrottleListener gets a callback via the ThrottleListener.notifyThrottleFound method.

This is a convenience version of the call, which uses system-specific logic to tell whether the address is a short or long form.

Specified by:

requestThrottle in interface ThrottleManager

Parameters:

address - The decoder address desired.

l - The ThrottleListener awaiting notification of a found throttle.

Returns:

True if the request will continue, false if the request will not be made. False may be returned if a the throttle is already in use.

requestThrottleSetup

public abstract void requestThrottleSetup(LocoAddress a,
                                          boolean control)

Abstract member to actually do the work of configuring a new throttle, usually via interaction with the DCC system

requestThrottleSetup

public void requestThrottleSetup(LocoAddress a)

Abstract member to actually do the work of configuring a new throttle, usually via interaction with the DCC system

cancelThrottleRequest

public void cancelThrottleRequest(int address,
                                  boolean isLong,
                                  ThrottleListener l)

Cancel a request for a throttle

Specified by:

cancelThrottleRequest in interface ThrottleManager

Parameters:

address - The decoder address desired.

isLong - True if this is a request for a DCC long (extended) address.

l - The ThrottleListener cancelling request for a throttle.

cancelThrottleRequest

public void cancelThrottleRequest(int address,
                                  ThrottleListener l)

Cancel a request for a throttle.

This is a convenience version of the call, which uses system-specific logic to tell whether the address is a short or long form.

Specified by:

cancelThrottleRequest in interface ThrottleManager

Parameters:

address - The decoder address desired.

l - The ThrottleListener cancelling request for a throttle.

failedThrottleRequest

public void failedThrottleRequest(DccLocoAddress address,
                                  String reason)

If the system-specific ThrottleManager has been unable to create the DCC throttle then it needs to be removed from the throttleListeners, otherwise any subsequent request for that address results in the address being reported as already in use, if singleUse is set. This also sends a notification message back to the requestor with a string reason as to why the request has failed.

Parameters:

address - The DCC Loco Address that the request failed on.

reason - A text string passed by the ThrottleManae as to why

notifyThrottleKnown

public void notifyThrottleKnown(DccThrottle throttle,
                                LocoAddress addr)

Handle throttle information when it's finally available, e.g. when a new Throttle object has been created.

This method creates a throttle for all ThrottleListeners of that address and notifies them via the ThrottleListener.notifyThrottleFound method.

hasDispatchFunction

public boolean hasDispatchFunction()

Check to see if the Dispatch Button should be enabled or not Default to true, override if necessary

Specified by:

hasDispatchFunction in interface ThrottleManager

supportedSpeedModes

public int supportedSpeedModes()

What speed modes are supported by this system? value should be xor of possible modes specifed by the DccThrottle interface

Specified by:

supportedSpeedModes in interface ThrottleManager

attachListener

public void attachListener(DccLocoAddress la,
                           PropertyChangeListener p)

Description copied from interface: ThrottleManager

Attach a PropertyChangeListener to a specific loco address, where the requesting code does not need or require control over the loco. If the loco address is not in the active in the list, then a new throttle will be created by the manager and the listener attached.

The propertyChangeListener will be notified if it has been attached to a loco address or not, via a propertyChange notification.

Specified by:

attachListener in interface ThrottleManager

Parameters:

la - - DccLocoAddress of the loco we wish to monitor

p - - PropertyChangeListener to attach to the throttle

removeListener

public void removeListener(DccLocoAddress la,
                           PropertyChangeListener p)

Description copied from interface: ThrottleManager

Remove a PropertyChangeListener to a specific loco address, where the requesting code has used attachListener to get notification of changes in a throttle.

The propertyChangeListener will be notified if it has been removed via a propertyChange notification.

Specified by:

removeListener in interface ThrottleManager

Parameters:

la - - DccLocoAddress of the loco we wish to monitor

p - - PropertyChangeListener to attachremove from the throttle

addressStillRequired

public boolean addressStillRequired(DccLocoAddress la)

Specified by:

addressStillRequired in interface ThrottleManager

releaseThrottle

public void releaseThrottle(DccThrottle t,
                            ThrottleListener l)

Description copied from interface: ThrottleManager

The specified Throttle Listener has finished using a given throttle and no longer requires access to it.

After releasing the throttle, the manager will perform further checks to see if it is in use by any other listeners or if there are any propertychangelisteners attached. If there are no other uses of the throttle then it is disposed of.

Normally, release ends with a call to dispose.

Specified by:

releaseThrottle in interface ThrottleManager

Parameters:

t - Throttle being released

l - Throttle Listener releasing the throttle

disposeThrottle

public boolean disposeThrottle(DccThrottle t,
                               ThrottleListener l)

Description copied from interface: ThrottleManager

Not for general use, see releaseThrottle and dispatchThrottle.

Dispose of object when finished it. This will free up hardware resource

Used for handling certain internal error conditions, where the object still exists but hardware is not associated with it.

After this, further usage of this Throttle object will result in a JmriException.

Specified by:

disposeThrottle in interface ThrottleManager

Parameters:

t - Throttle being released

l - Throttle Listener releasing the throttle

Returns:

true if the throttle has been disposed of.

dispatchThrottle

public void dispatchThrottle(DccThrottle t,
                             ThrottleListener l)

Description copied from interface: ThrottleManager

The throttle listener has finished with the specific Throttle and is is available for reuse/reallocation by somebody else. If possible, tell the layout that this locomotive has been dispatched to another user. Not all layouts will implement this, in which case it is synomous with release();

Normally, dispatch ends with a call to dispose.

Specified by:

dispatchThrottle in interface ThrottleManager

Parameters:

t - Throttle being released

l - Throttle Listener releasing the throttle

addressReleased

protected boolean addressReleased(DccLocoAddress la,
                                  ThrottleListener l)

getThrottleInfo

public Object getThrottleInfo(DccLocoAddress la,
                              String item)

Description copied from interface: ThrottleManager

Provides a Proxy method to return the SpeedSetting, Direction, Function Settings, of a throttle, where the requesting code has used the attachListener to only be notified of changes in the throttle and not control it.

Valid values for item are IsForward SpeedSetting SpeedIncrement SpeedStepMode F0-F28

Specified by:

getThrottleInfo in interface ThrottleManager

Parameters:

la - DccLocoAddress that we wish interrogate

item - A string of the item we wish to know the value of.

Returns:

the value as an objet, if the loco address has not been assigned to a throttle or the item value is not valid, null is returned.