org.ka2ddo.yaac.core

Class Macros

java.lang.Object

org.ka2ddo.yaac.core.Macros

public class Macros
extends java.lang.Object

This class collects macro values that can be substituted into text output (such as status messages, pre-defined text messages, etc.) when referenced. The macros appear in the text messages as curly braces surrounding the text "M:macroname", so as to not conflict with other macros used elsewhere im YAAC.

Since:

PROVIDER_API_VERSION == 50

Author:

Andrew Pavlin, KA2DDO

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Macros.MacroChangeListener Interface for listeners who want to know if a macro is changed.
static class	Macros.MacroInfo The class containing all the data associated with a macro name.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	MACRO_PREFS_NAME The expected name String for a sub-node of the YAAC Preferences node to contain saved macro values.

Method Summary

Modifier and Type	Method and Description
void	addMacroChangeListener(Macros.MacroChangeListener listener) Register a listener to be informed when macros are changed.
java.lang.String	applyMacros(java.lang.String format) Insert macro values into a String.
static Macros	getInstance() Get the Macros singleton.
java.lang.String	getMacroLocalizedDescription(java.lang.String macroName) Get the localized description of the purpose of this macro.
java.util.Set<java.lang.String>	getMacroNameSet() Get a Set of all the currently known macros.
java.lang.String	getMacroValue(java.lang.String macroName) Get the current value of a macro.
void	loadPersistedMacros(java.util.prefs.Preferences prefs) Load macros from the specified Preferences object.
void	removeMacroChangeListener(Macros.MacroChangeListener listener) Unregister a listener to no longer be informed when macros are changed.
void	setLocalizedMacroDescription(java.lang.String macroName, java.lang.String localizedDescription) Set the localized description of the purpose of this macro.
java.lang.String	setMacro(java.lang.String macroName, java.lang.String value) Set the value for a named macro.
java.lang.String	setPersistedMacro(java.lang.String macroName, java.lang.String value, java.util.prefs.Preferences prefs) Set the value for a named macro, and save it for use after YAAC restarts.

Methods inherited from class java.lang.Object

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

Field Detail

MACRO_PREFS_NAME

public static final java.lang.String MACRO_PREFS_NAME

The expected name String for a sub-node of the YAAC Preferences node to contain saved macro values.

Since:

PROVIDER_API_VERSION == 50

See Also:

setPersistedMacro(String, String, Preferences), loadPersistedMacros(Preferences), Constant Field Values

Method Detail

getInstance

public static Macros getInstance()

Get the Macros singleton.

Returns:

Macros instance

Since:

PROVIDER_API_VERSION == 50

setMacro

public java.lang.String setMacro(java.lang.String macroName,
                                 java.lang.String value)

Set the value for a named macro. Note if the value is changed, registered listeners to the Macros service will be notified of the change.

Parameters:

macroName - String name of a macro (should not contain whitespace)

value - String value of the macro (should be short, so as to not cause APRS packets to exceed maximum packet length)

Returns:

the previous value of the macro (may be null if unset)

Since:

PROVIDER_API_VERSION == 50

setPersistedMacro

public java.lang.String setPersistedMacro(java.lang.String macroName,
                                          java.lang.String value,
                                          java.util.prefs.Preferences prefs)

Set the value for a named macro, and save it for use after YAAC restarts. Note if the value is changed, registered listeners to the Macros service will be notified of the change.

The prefs parameter should typically be YAAC.getPreferences().node(Macros.MACROS_PREFS_NAME)

Parameters:

macroName - String name of a macro (should not contain whitespace)

value - String value of the macro (should be short, so as to not cause APRS packets to exceed maximum packet length)

prefs - Java Preferences object to store the macro in, or null to not persist the macro value

Returns:

the previous value of the macro (may be null if unset)

Since:

PROVIDER_API_VERSION == 50

See Also:

YAAC.getPreferences(), MACRO_PREFS_NAME

loadPersistedMacros

public void loadPersistedMacros(java.util.prefs.Preferences prefs)
                         throws java.util.prefs.BackingStoreException

Load macros from the specified Preferences object. Intended for use at YAAC startup.

The prefs parameter should typically be YAAC.getPreferences().node(Macros.MACROS_PREFS_NAME)

Parameters:

prefs - Preferences object storing the saved macros

Throws:

java.util.prefs.BackingStoreException - if problem reading the saved macro values

Since:

PROVIDER_API_VERSION == 50

See Also:

YAAC.getPreferences(), MACRO_PREFS_NAME

setLocalizedMacroDescription

public void setLocalizedMacroDescription(java.lang.String macroName,
                                         java.lang.String localizedDescription)

Set the localized description of the purpose of this macro. Optional, but useful for manual macro defining plugins.

Parameters:

macroName - String name of a macro (should not contain whitespace)

localizedDescription - String of description of the macro's purpose

Since:

PROVIDER_API_VERSION == 50

getMacroValue

public java.lang.String getMacroValue(java.lang.String macroName)

Get the current value of a macro.

Parameters:

macroName - String name of a macro (should not contain whitespace)

Returns:

String value of the macro, or null if the macro has not been defined

Since:

PROVIDER_API_VERSION == 50

getMacroLocalizedDescription

public java.lang.String getMacroLocalizedDescription(java.lang.String macroName)

Get the localized description of the purpose of this macro. Optional, but useful for manual macro defining plugins.

Parameters:

macroName - String name of a macro (should not contain whitespace)

Returns:

String of description of the macro's purpose, or empty String if unspecified

Since:

PROVIDER_API_VERSION == 50

getMacroNameSet

public java.util.Set<java.lang.String> getMacroNameSet()

Get a Set of all the currently known macros. The Strings in this set may be used to query the macro repository.

Returns:

Set of macro name Strings

Since:

PROVIDER_API_VERSION == 50

addMacroChangeListener

public void addMacroChangeListener(Macros.MacroChangeListener listener)

Register a listener to be informed when macros are changed.

Parameters:

listener - MacroChangeListener implementation to register

Since:

PROVIDER_API_VERSION == 50

removeMacroChangeListener

public void removeMacroChangeListener(Macros.MacroChangeListener listener)

Unregister a listener to no longer be informed when macros are changed.

Parameters:

listener - MacroChangeListener implementation to unregister

Since:

PROVIDER_API_VERSION == 50

applyMacros

public java.lang.String applyMacros(java.lang.String format)

Insert macro values into a String. The String contains references to macros in the form {M:macroname}. Such patterns are replaced with the current value of the named macro, or removed entirely if the specified macro is undefined or set to an empty String value.

Parameters:

format - String possibly containing macro references

Returns:

String with the macro values substituted for the macro references

Since:

PROVIDER_API_VERSION == 50