jmri
Interface ThrottleManager

All Known Implementing Classes:

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

public interface ThrottleManager

Interface for allocating Throttle objects.

"Address" is interpreted in the context of the DCC implementation. Different systems will distinquish between short and long addresses in different ways.

When the allocated Throttle is no longer needed, it is told that it's released. If a specific ThrottleManager and/or Throttle implementation needs to keep track of that operation, it is handled internally.

This file is part of JMRI.

JMRI is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation. See the "COPYING" file for a copy of this license.

JMRI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Author:

Glen Oberhauser, Bob Jacobsen Copyright 2006

Method Summary

boolean	addressStillRequired(DccLocoAddress la)
boolean	addressTypeUnique() Are there not any ambiguous addresses (short vs long) on this system?
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.
boolean	canBeLongAddress(int address) Check to see if a specific number is a valid long address on this system
boolean	canBeShortAddress(int address) Check to see if a specific number is a valid short address on this system
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.
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
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 address, ThrottleListener l) Request a throttle, given a decoder address.
boolean	requestThrottle(int address, boolean isLong, 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.
int	supportedSpeedModes() What speed modes are supported by this system?

Method Detail

requestThrottle

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.

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.

requestThrottle

boolean requestThrottle(int address,
                        boolean isLong,
                        ThrottleListener l)

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.

Parameters:

address - The decoder address desired.

isLong - 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

boolean requestThrottle(DccLocoAddress 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.

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.

cancelThrottleRequest

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.

Parameters:

address - The decoder address desired.

l - The ThrottleListener cancelling request for a throttle.

cancelThrottleRequest

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

Cancel a request for a throttle.

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.

hasDispatchFunction

boolean hasDispatchFunction()

Check to see if the Dispatch Button should be enabled or not

canBeLongAddress

boolean canBeLongAddress(int address)

Check to see if a specific number is a valid long address on this system

canBeShortAddress

boolean canBeShortAddress(int address)

Check to see if a specific number is a valid short address on this system

addressTypeUnique

boolean addressTypeUnique()

Are there not any ambiguous addresses (short vs long) on this system?

supportedSpeedModes

int supportedSpeedModes()

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

getThrottleInfo

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.

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

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.

addressStillRequired

boolean addressStillRequired(DccLocoAddress la)

releaseThrottle

void releaseThrottle(DccThrottle t,
                     ThrottleListener l)

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.

Parameters:

t - Throttle being released

l - Throttle Listener releasing the throttle

disposeThrottle

boolean disposeThrottle(DccThrottle t,
                        ThrottleListener l)

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.

Parameters:

t - Throttle being released

l - Throttle Listener releasing the throttle

Returns:

true if the throttle has been disposed of.

dispatchThrottle

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

Parameters:

t - Throttle being released

l - Throttle Listener releasing the throttle

attachListener

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

Parameters:

la - - DccLocoAddress of the loco we wish to monitor

p - - PropertyChangeListener to attach to the throttle

removeListener

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.

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

Parameters:

la - - DccLocoAddress of the loco we wish to monitor

p - - PropertyChangeListener to attachremove from the throttle