java.lang.Object
- ca.cgjennings.apps.arkham.plugins.PluginRoot

All Implemented Interfaces:

java.lang.Comparable<PluginRoot>
```
public class PluginRoot
extends java.lang.Object
implements java.lang.Comparable<PluginRoot>
```
Represents the information stored in a plug-in bundle's root file. This includes the bundle's CatalogID, the plug-in objects contained in the bundle, the bundle's startup priority, and other properties. If the bundle is not stored in a plain format, creating a PluginRoot for the bundle will convert it in place.

Since:

2.1

Author:

Chris Jennings

Field Summary

Fields
Modifier and Type	Field	Description
`static java.lang.String`	`CLASS_PREFIX`	The prefix that may explicitly prefix a compiled plug-in entry.
`static java.lang.String`	`CLIENT_KEY_CATALOG_DESCRIPTION`	The plug-in description that will be shown in the catalogue if a catalogue listing is extracted from this root file.
`static java.lang.String`	`CLIENT_KEY_CATALOG_NAME`	The plug-in name that will be shown in the catalogue if a catalogue listing is extracted from this root file.
`static java.lang.String`	`CLIENT_KEY_DESCRIPTION`	The description of the plug-in bundle.
`static java.lang.String`	`CLIENT_KEY_GAME_LANGUAGES`	A comma-separated list of game locales supported by the plug-in.
`static java.lang.String`	`CLIENT_KEY_IMAGE`	Resource URL string of a representative image for the bundle.
`static java.lang.String`	`CLIENT_KEY_NAME`	The name of the plug-in bundle.
`static java.lang.String`	`CLIENT_KEY_UI_LANGUAGES`	A comma-separated list of interface locales supported by the plug-in.
`static java.lang.String`	`KEY_ID`	The property key in the root file that describes the catalog ID.
`static java.lang.String`	`KEY_INSTALL_SCRIPT`	Property key that identifies a script to run after installing and before uninstalling the plug-in bundle.
`static java.lang.String`	`KEY_PRIORITY`	The property key that defines the bundle's load priority.
`static int`	`PRIORITY_DEFAULT`	The default priority used when no value is specified in the root file.
`static int`	`PRIORITY_EXPANSION`	A predefined priority value used when the value of the priority key is the string "EXPANSION".
`static int`	`PRIORITY_GAME`	A predefined priority value used when the value of the priority key is the string "GAME".
`static int`	`PRIORITY_HIGH`	A predefined priority value used when the value of the priority key is the string "HIGH".
`static int`	`PRIORITY_LOW`	A predefined priority value used when the value of the priority key is the string "LOW".
`static int`	`PRIORITY_NORMAL`	A predefined priority value used when the value of the priority key is the string "NORMAL".
`static java.lang.String`	`ROOT_FILE`	The name of the file that contains the plug-in root in a bundle file ("eons-plugin").
`static java.lang.String`	`SCRIPT_PREFIX`	The prefix that may explicitly prefix a scripted plug-in entry.

Constructor Summary

Constructors
Constructor	Description
`PluginRoot(PluginBundle pb)`	Read root file information from a plug-in bundle.
`PluginRoot(java.io.File file)`	Read root file information directly from a root file, such as one stored in a project folder.
`PluginRoot(java.lang.String rootSettings)`	Creates a root file by parsing a string that uses the root file format.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`void`	`addPluginIdentifier(java.lang.String id)`	Adds a new plug-in identifier to the list of identifiers.
`int`	`compareTo(PluginRoot root)`	Compares two roots based on their priorities.
`static java.lang.String`	`decoratePluginIdentifier(java.lang.String pid)`	Converts a plug-in identifier into a short, human-friendly form.
`boolean`	`equals(java.lang.Object obj)`	Returns `true` if and only if the specified object is a root file with the same string representation.
`PluginBundle`	`getBundle()`	Returns the plug-in bundle that this root belongs to, or `null` if this root object was not created from a bundle.
`CatalogID`	`getCatalogID()`	Returns the catalog ID for this root file, or `null` if none is defined.
`java.lang.String`	`getClientProperty(java.lang.String key)`	Returns the value of a client property, or `null` if the property is not defined.
`java.util.Set<java.lang.String>`	`getClientPropertyKeys()`	Returns an immutable set of all client property keys that are defined at the time the method is called.
`java.lang.String`	`getComments()`	Returns the comment lines located at the top of the root file, if any.
`java.lang.String[]`	`getErrors()`	Returns an array of messages describing syntax errors in the file.
`java.lang.String`	`getInstallerIdentifier()`	Returns the identifier of the installer class or script for this root file.
`java.lang.String`	`getLocalizedClientProperty(java.lang.String key)`	Returns the value of a client property, or `null` if the property is not defined.
`java.lang.String[]`	`getPluginIdentifiers()`	Returns an array of the compiled class and script identifiers that represent plug-ins (or themes) stored in this bundle.
`int`	`getPriority()`	Returns the bundle's load priority as an integer.
`int`	`hashCode()`	Returns a hash code for this root file.
`static java.lang.String`	`normalizePluginIdentifier(java.lang.String pid)`	Converts a plug-in identifier into the normalized form expected by the plug-in system.
`void`	`putClientProperty(java.lang.String key, java.lang.String value)`	Sets the value of a client property, or removes the property if `value` is `null`.
`void`	`removePluginIdentifier(java.lang.String id)`	Removes a new plug-in identifier from the list of identifiers.
`void`	`setCatalogID(CatalogID id)`	Sets the catalog ID for this root file.
`void`	`setComments(java.lang.String comments)`	Sets the text of a comment that will be placed at the top of the root file.
`void`	`setInstallerIdentifier(java.lang.String install)`	Sets the identifier of the installer class or script to run during installation or uninstallation of the associated plug-in bundle.
`void`	`setPluginIdentifiers(java.lang.String[] ids)`	Replaces the existing plug-in identifiers with the identifiers in the specified array.
`void`	`setPriority(int pri)`	Sets the bundle's load priority from an integer value.
`java.lang.String`	`toString()`	Returns a string that is equivalent to the code in the original root file, though not necessarily identical.
`void`	`updateBundle()`	Updates the plug-in bundle that this plug-in was created from so that its root file matches the current state of this root.
`void`	`writeToBundleArchive(java.util.zip.ZipOutputStream out)`	Writes this plug-in root as a new archive file entry (with the name `eons-plugin`) to an archive output stream.
`void`	`writeToFile(java.io.File f)`	Writes this plug-in root to a UTF-8 encoded text file.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - ROOT_FILE
```
public static final java.lang.String ROOT_FILE
```
    The name of the file that contains the plug-in root in a bundle file ("eons-plugin").
    
    See Also:
    
    Constant Field Values
  - SCRIPT_PREFIX
```
public static final java.lang.String SCRIPT_PREFIX
```
    The prefix that may explicitly prefix a scripted plug-in entry. Present in normal form.
    
    See Also:
    
    Constant Field Values
  - CLASS_PREFIX
```
public static final java.lang.String CLASS_PREFIX
```
    The prefix that may explicitly prefix a compiled plug-in entry. Not present in normal form.
    
    See Also:
    
    Constant Field Values
  - KEY_ID
```
public static final java.lang.String KEY_ID
```
    The property key in the root file that describes the catalog ID.
    
    See Also:
    
    Constant Field Values
  - KEY_PRIORITY
```
public static final java.lang.String KEY_PRIORITY
```
    The property key that defines the bundle's load priority. When a group of plug-ins is discovered, the priority values will be used to determine the order that the plug-ins are installed in. This is mainly useful for extensions, where an extension that installs additional material for a game might rely on the game plug-in already being installed. The priority is also used to group plug-ins in the Toolbox menu.
    
    See Also:
    
    setPriority(int), Constant Field Values
  - KEY_INSTALL_SCRIPT
```
public static final java.lang.String KEY_INSTALL_SCRIPT
```
    Property key that identifies a script to run after installing and before uninstalling the plug-in bundle.
    
    See Also:
    
    InstallationActions, Constant Field Values
  - PRIORITY_GAME
```
public static final int PRIORITY_GAME
```
    A predefined priority value used when the value of the priority key is the string "GAME". Equivalent to the value 100.
    
    See Also:
    
    Constant Field Values
  - PRIORITY_EXPANSION
```
public static final int PRIORITY_EXPANSION
```
    A predefined priority value used when the value of the priority key is the string "EXPANSION". Equivalent to the value 500.
    
    See Also:
    
    Constant Field Values
  - PRIORITY_HIGH
```
public static final int PRIORITY_HIGH
```
    A predefined priority value used when the value of the priority key is the string "HIGH". Equivalent to the value 1000.
    
    See Also:
    
    Constant Field Values
  - PRIORITY_NORMAL
```
public static final int PRIORITY_NORMAL
```
    A predefined priority value used when the value of the priority key is the string "NORMAL". Equivalent to the value 5000.
    
    See Also:
    
    Constant Field Values
  - PRIORITY_LOW
```
public static final int PRIORITY_LOW
```
    A predefined priority value used when the value of the priority key is the string "LOW". Equivalent to the value 10000.
    
    See Also:
    
    Constant Field Values
  - PRIORITY_DEFAULT
```
public static final int PRIORITY_DEFAULT
```
    The default priority used when no value is specified in the root file.
    
    See Also:
    
    Constant Field Values
  - CLIENT_KEY_NAME
```
public static final java.lang.String CLIENT_KEY_NAME
```
    The name of the plug-in bundle. The name returned by the plug-in(s) takes precedence, so this is useful mainly for library bundles.
    
    See Also:
    
    Constant Field Values
  - CLIENT_KEY_DESCRIPTION
```
public static final java.lang.String CLIENT_KEY_DESCRIPTION
```
    The description of the plug-in bundle. The description returned by the plug-in(s) takes precedence, so this is useful mainly for library bundles.
    
    See Also:
    
    Constant Field Values
  - CLIENT_KEY_IMAGE
```
public static final java.lang.String CLIENT_KEY_IMAGE
```
    Resource URL string of a representative image for the bundle. Used for library bundles, since they contain no plug-ins.
    
    See Also:
    
    Constant Field Values
  - CLIENT_KEY_UI_LANGUAGES
```
public static final java.lang.String CLIENT_KEY_UI_LANGUAGES
```
    A comma-separated list of interface locales supported by the plug-in.
    
    See Also:
    
    Constant Field Values
  - CLIENT_KEY_GAME_LANGUAGES
```
public static final java.lang.String CLIENT_KEY_GAME_LANGUAGES
```
    A comma-separated list of game locales supported by the plug-in.
    
    See Also:
    
    Constant Field Values
  - CLIENT_KEY_CATALOG_NAME
```
public static final java.lang.String CLIENT_KEY_CATALOG_NAME
```
    The plug-in name that will be shown in the catalogue if a catalogue listing is extracted from this root file.
    
    See Also:
    
    Constant Field Values
  - CLIENT_KEY_CATALOG_DESCRIPTION
```
public static final java.lang.String CLIENT_KEY_CATALOG_DESCRIPTION
```
    The plug-in description that will be shown in the catalogue if a catalogue listing is extracted from this root file.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - PluginRoot
```
public PluginRoot(PluginBundle pb)
           throws java.io.IOException
```
    Read root file information from a plug-in bundle. Typically, this constructor is not used directly. Instead, the root is obtained using PluginBundle.getPluginRoot(), which caches the result.
    
    Parameters:
    
    pb - the bundle file that contains the root
    
    Throws:
    
    java.io.IOException - if there is an I/O error while parsing the file
    
    java.lang.NullPointerException - if file is null
  - PluginRoot
```
public PluginRoot(java.io.File file)
           throws java.io.IOException
```
    Read root file information directly from a root file, such as one stored in a project folder.
    
    Parameters:
    
    file - the UTF-8 encoded text file that contains the root
    
    Throws:
    
    java.io.IOException - if there is an I/O error while parsing the file
    
    java.lang.NullPointerException - if file is null
  - PluginRoot
```
public PluginRoot(java.lang.String rootSettings)
```
    Creates a root file by parsing a string that uses the root file format.
    
    Parameters:
    
    rootSettings - the root file code
    
    Throws:
    
    java.lang.NullPointerException - if rootSettings is null
- Method Detail
  - normalizePluginIdentifier
```
public static java.lang.String normalizePluginIdentifier(java.lang.String pid)
```
    Converts a plug-in identifier into the normalized form expected by the plug-in system. Scripts must start with "script:" followed by a "res:" URL; classes must not start with "class:".
    Note: Identifiers returned by getPluginIdentifiers() will already be in normal form.
    The normalization process consists of the following:
    
    Entries that end with ".js" and do not start with "class:" are treated as scripts and will start with "script:" if they did not previously.
    Entries that start with "res://" are treated as scripts and will start with "script:" if they did not previously.
    All scripts will identify the script location by res:// URL.
    Class entries that start with "class:" will have this prefix removed.
    Class entries that end with ".class" or ".java" will have this suffix removed.
    Parameters:
    
    pid - the plug-in identifier (line from a root file that identifies a plug-in)
    
    Returns:
    
    the identifier in normal form
    
    Throws:
    
    java.lang.IllegalArgumentException - if the identifier is not valid
  - decoratePluginIdentifier
```
public static java.lang.String decoratePluginIdentifier(java.lang.String pid)
```
    Converts a plug-in identifier into a short, human-friendly form. The decorated format is used by this class to create externalized identifiers (as with toString()). The decorated form is equivalent to the normalized form except that scripts will not start with "script:". (This is acceptable since in normal form they will start with "res://", which is not valid in a class name.)
    
    Parameters:
    
    pid - the identifier
    
    Returns:
    
    the decorated identifier
    
    Throws:
    
    java.lang.IllegalArgumentException - if the identifier is invalid
    
    See Also:
    
    normalizePluginIdentifier(java.lang.String)
  - getBundle
```
public PluginBundle getBundle()
```
    Returns the plug-in bundle that this root belongs to, or null if this root object was not created from a bundle.
    
    Returns:
    
    the bundle associated with this root
  - getComments
```
public java.lang.String getComments()
```
    Returns the comment lines located at the top of the root file, if any. The returned text will include the comment marker characters ('#' or '!').
    
    Returns:
    
    the content of the comment block at the top of the file, or null
    
    See Also:
    
    setComments(java.lang.String)
  - setComments
```
public void setComments(java.lang.String comments)
```
    Sets the text of a comment that will be placed at the top of the root file. Any existing comment block will be replaced. Lines in the comment string should be separated by a newline character. Any lines that do not already start with a comment marker ('#' or '!') will cause an IllegalArgumentException to be thrown.
    
    Parameters:
    
    comments - the comment text to set, or null to clear the comment block
    
    See Also:
    
    getComments()
  - getPriority
```
public int getPriority()
```
    Returns the bundle's load priority as an integer.
    
    Returns:
    
    the load priority value
  - setPriority
```
public void setPriority(int pri)
```
    Sets the bundle's load priority from an integer value. Bundles are loaded in order of their priority values, from lowest to highest. That is, setting this to a lower value gives the bundle a higher load priority. If the priority value corresponds to one of the special named priorities ("GAME", "EXPANSION, "HIGH", "NORMAL", "LOW"), then writing the root file will write the value as the keyword rather than an integer string. If the value corresponds to the default load priority, then the key will be omitted altogether.
    
    Parameters:
    
    pri - the new priority value
    
    See Also:
    
    KEY_PRIORITY, PRIORITY_GAME, PRIORITY_EXPANSION, PRIORITY_HIGH, PRIORITY_NORMAL, PRIORITY_LOW, PRIORITY_DEFAULT
  - getCatalogID
```
public CatalogID getCatalogID()
```
    Returns the catalog ID for this root file, or null if none is defined.
    
    Returns:
    
    the ID for the bundle that this root file is (or will be) for
  - setCatalogID
```
public void setCatalogID(CatalogID id)
```
    Sets the catalog ID for this root file.
    
    Parameters:
    
    id - the new catalog ID for the root file's bundle
    
    See Also:
    
    getCatalogID()
  - getInstallerIdentifier
```
public java.lang.String getInstallerIdentifier()
```
    Returns the identifier of the installer class or script for this root file.
    
    Returns:
    
    the installation script resource, or null
    
    See Also:
    
    setInstallerIdentifier(java.lang.String)
  - setInstallerIdentifier
```
public void setInstallerIdentifier(java.lang.String install)
```
    Sets the identifier of the installer class or script to run during installation or uninstallation of the associated plug-in bundle. Setting this to null will clear the current installer, if any.
    
    Parameters:
    
    install - the installation script identifier
    
    See Also:
    
    getInstallerIdentifier(), KEY_INSTALL_SCRIPT
  - getPluginIdentifiers
```
public java.lang.String[] getPluginIdentifiers()
```
    Returns an array of the compiled class and script identifiers that represent plug-ins (or themes) stored in this bundle.
    
    Returns:
    
    an array of the stored plug-in identifiers
  - setPluginIdentifiers
```
public void setPluginIdentifiers(java.lang.String[] ids)
```
    Replaces the existing plug-in identifiers with the identifiers in the specified array.
    
    Parameters:
    
    ids - an array of plug-in identifiers
    
    Throws:
    
    java.lang.NullPointerException - if the array or any of its elements is null
  - addPluginIdentifier
```
public void addPluginIdentifier(java.lang.String id)
```
    Adds a new plug-in identifier to the list of identifiers. Does nothing if the plug-in is already listed.
    
    Parameters:
    
    id - the identifier to add
    
    Throws:
    
    java.lang.NullPointerException - if the identifier is null
  - removePluginIdentifier
```
public void removePluginIdentifier(java.lang.String id)
```
    Removes a new plug-in identifier from the list of identifiers. Does nothing if the plug-in is not listed.
    
    Parameters:
    
    id - the identifier to remove
    
    Throws:
    
    java.lang.NullPointerException - if the identifier is null
  - putClientProperty
```
public void putClientProperty(java.lang.String key,
                              java.lang.String value)
```
    Sets the value of a client property, or removes the property if value is null.
    
    Parameters:
    
    key - the name of the client key
    
    value - the value of the client key
  - getClientProperty
```
public java.lang.String getClientProperty(java.lang.String key)
```
    Returns the value of a client property, or null if the property is not defined.
    
    Parameters:
    
    key - the name of the client property
    
    Returns:
    
    the value of the named property, or null
  - getLocalizedClientProperty
```
public java.lang.String getLocalizedClientProperty(java.lang.String key)
```
    Returns the value of a client property, or null if the property is not defined. The property will be localized for the user interface language, if possible.
    
    Parameters:
    
    key - the name of the client property
    
    Returns:
    
    the value of the named property, or null
  - getClientPropertyKeys
```
public java.util.Set<java.lang.String> getClientPropertyKeys()
```
    Returns an immutable set of all client property keys that are defined at the time the method is called.
    
    Returns:
    
    keys available as client properties
  - getErrors
```
public java.lang.String[] getErrors()
```
    Returns an array of messages describing syntax errors in the file. The returned array will contain one element for each error.
    
    Returns:
    
    a (possibly empty) array of error messages
  - writeToBundleArchive
```
public void writeToBundleArchive(java.util.zip.ZipOutputStream out)
                          throws java.io.IOException
```
    Writes this plug-in root as a new archive file entry (with the name eons-plugin) to an archive output stream.
    
    Parameters:
    
    out - the archive stream
    
    Throws:
    
    java.io.IOException - if an I/O or Zip error occurs while writing the entry
  - writeToFile
```
public void writeToFile(java.io.File f)
                 throws java.io.IOException
```
    Writes this plug-in root to a UTF-8 encoded text file.
    
    Parameters:
    
    f - the file to write to
    
    Throws:
    
    java.io.IOException - if an I/O exception occurs
  - updateBundle
```
public void updateBundle()
                  throws java.io.IOException
```
    Updates the plug-in bundle that this plug-in was created from so that its root file matches the current state of this root. This may be a lengthy operation, as the bundle must first be copied and then the original file overwritten.
    
    Throws:
    
    java.io.IOException - if an I/O or Zip error occurs while updating the archive
    
    java.lang.IllegalStateException - if this root file was not created from a bundle
  - compareTo
```
public int compareTo(PluginRoot root)
```
    Compares two roots based on their priorities. This implements a natural sort order for plug-in roots that sorts them into their preferred order for installation.
    
    Specified by:
    
    compareTo in interface java.lang.Comparable<PluginRoot>
    
    Parameters:
    
    root - the plug-in root to compare this one with
    
    Returns:
    
    a comparison value that compares the priorities of both PluginRoots
  - toString
```
public java.lang.String toString()
```
    Returns a string that is equivalent to the code in the original root file, though not necessarily identical. It may leave out some comments, blank lines, or invalid lines, may store keys in a different order, and may use more modern syntax where applicable.
    
    Overrides:
    
    toString in class java.lang.Object
  - equals
```
public boolean equals(java.lang.Object obj)
```
    Returns true if and only if the specified object is a root file with the same string representation.
    
    Overrides:
    
    equals in class java.lang.Object
    
    Parameters:
    
    obj - the object to compare this object to
    
    Returns:
    
    true if the object represents a root file with the same properties
  - hashCode
```
public int hashCode()
```
    Returns a hash code for this root file.
    
    Overrides:
    
    hashCode in class java.lang.Object
    
    Returns:
    
    a hash code value

Class PluginRoot

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ROOT_FILE

SCRIPT_PREFIX

CLASS_PREFIX

KEY_ID

KEY_PRIORITY

KEY_INSTALL_SCRIPT

PRIORITY_GAME

PRIORITY_EXPANSION

PRIORITY_HIGH

PRIORITY_NORMAL

PRIORITY_LOW

PRIORITY_DEFAULT

CLIENT_KEY_NAME

CLIENT_KEY_DESCRIPTION

CLIENT_KEY_IMAGE

CLIENT_KEY_UI_LANGUAGES

CLIENT_KEY_GAME_LANGUAGES

CLIENT_KEY_CATALOG_NAME

CLIENT_KEY_CATALOG_DESCRIPTION

Constructor Detail

PluginRoot

PluginRoot

PluginRoot

Method Detail

normalizePluginIdentifier

decoratePluginIdentifier

getBundle

getComments

setComments

getPriority

setPriority

getCatalogID

setCatalogID

getInstallerIdentifier

setInstallerIdentifier

getPluginIdentifiers

setPluginIdentifiers

addPluginIdentifier

removePluginIdentifier

putClientProperty

getClientProperty

getLocalizedClientProperty

getClientPropertyKeys

getErrors

writeToBundleArchive

writeToFile

updateBundle

compareTo

toString

equals

hashCode