java.lang.Object
- ca.cgjennings.apps.arkham.plugins.catalog.Catalog

```
public class Catalog
extends java.lang.Object
```
A collection of Listings that describe plug-ins from a download source. The source may be local or, more typically, located over a network. The catalog can determine whether its listings match installed plug-ins, and if so compare their versions to determine if the listing is newer. Listings in the catalog can be "flagged" for installation, and flagged listings can be downloaded and installed automatically.
Catalogs can be described using plain text files, and a catalog in this format can be instantiated from a remote URL. On a server, a catalog and its plug-ins would be located together in a single folder. The catalog would be stored in this folder as catalog.txt, and the listings in the catalog would point to the file names of plug-in bundles stored in the folder. To create the catalog locally, it would be constructed with the URL of the base folder. The constructor will download the catalog, and the base URL will be used to download any installed plug-ins.
Catalog listings may be marked as "hidden". In this case, they are placed at the end of a catalog when it is loaded, after all regular listings. When iterating over the catalog, if the catalog size is determined using size(), then you will not see hidden listings. To iterate over all listings, including hidden listings, use trueSize(). Hidden listings are usually added to a catalog when it contains components that are required by other components but not useful by themselves. They can also be used to link to required components that are in other catalogs. For example, this could be used to create a private catalog that contains a component that requires a plug-in from another site:
```
 url = ./myplugin.seplugin
 name = My Plug-in
 requires = CATALOGUEID{thatid}
 id = CATALOGUEID{thisid}

 hidden
 url = http://anothersite.org/se/plugins/RequiredPlugin.seplugin
 name = Required Plugin
 id = CATALOGUEID{thatid}
 
```
Since:

2.1

Author:

Chris Jennings

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`static class`	`Catalog.CatalogIsLockedException`	This exception is thrown when you attempt to download a catalog that is currently being updated.
`static class`	`Catalog.VersioningState`	An enumeration of the possible versioning states for a listing.

Constructor Summary

Constructors
Constructor	Description
`Catalog()`	Creates a new, empty catalog with a `null` base URL.
`Catalog(java.net.URL base)`	Loads a catalog from a base URL.
`Catalog(java.net.URL base, boolean allowCache, javax.swing.JProgressBar feedback)`	Loads a catalog from a base URL.
`Catalog(java.net.URL base, java.util.Collection<Listing> listings)`	Creates a catalog from a collection of `Listing`s.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`void`	`add(Listing li)`	Adds a listing to the catalog.
`static void`	`addPostInstallationHook(java.lang.Runnable h)`	Adds a new post-installation hook.
`java.util.BitSet`	`determineInstallationRequirements()`	Determines the installation requirements set for the plug-ins that are currently flagged for installation.
`int`	`findListingByUUID(java.util.UUID uuid)`	Returns the index of the listing in this catalog that has the requested UUID.
`Listing`	`get(int n)`	Returns the listing at index `n` in the catalog.
`java.net.URL`	`getBaseURL()`	Returns the base URL used to resolve the location of plug-in bundles listed in the catalog.
`boolean`	`getInstallFlag(int n)`	Returns `true` if the listing at the indicated index is flagged for installation.
`int`	`getInstallFlagCount()`	Returns a count of the number of plug-ins that are currently flagged for installation from this catalog.
`static Catalog`	`getLocalCopy()`	Returns the locally cached catalog, if any.
`Catalog.VersioningState`	`getVersioningState(int n)`	Compares the listing at index `n` with the set of installed plug-ins and returns a `Catalog.VersioningState` value that describes the relative version of the installed plug-in, if any.
`boolean`	`installFlaggedPlugins()`	Attempt to download and install all plug-ins that are currently flagged for installation.
`boolean`	`isRestartRequiredAfterInstall()`	Returns `true` if a restart (of the application) would be required after the currently selected plug-ins are installed.
`void`	`reload()`	Reload the catalog from the source.
`boolean`	`remove(java.util.UUID uuid)`	Removes the listing whose catalog ID matches the provided UUID.
`static void`	`removePostInstallationHook(java.lang.Runnable h)`	Removes a previously installed post-installation hook.
`protected void`	`setBaseURL(java.net.URL url)`	Subclasses may use this to set a custom base URL.
`void`	`setInstallFlag(int n, boolean install)`	Mark the listing at index `n` for installation.
`int`	`size()`	Returns the number of listings in the catalog, not counting any hidden listings.
`int`	`trueSize()`	Returns the number of listings in the catalog, including any hidden listings.
`void`	`write(java.io.OutputStream out)`	Write the catalog to a stream as a catalog description file.

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

- Constructor Detail
  - Catalog
```
public Catalog()
```
    Creates a new, empty catalog with a null base URL. This can be useful as a temporary placeholder in a UI while downloading a catalog, or it can be used by subclasses.
  - Catalog
```
public Catalog(java.net.URL base,
               java.util.Collection<Listing> listings)
```
    Creates a catalog from a collection of Listings. This is normally used to create a temporary local catalog in order to write a catalog description file. The base URL is not required unless installation is attempted, and may be null.
  - Catalog
```
public Catalog(java.net.URL base)
        throws java.io.IOException
```
    Loads a catalog from a base URL. The URL of the catalog will be the base URL with "catalog.txt" appended.
    
    Parameters:
    
    base - the URL to load the catalog from
    
    Throws:
    
    java.io.IOException - if an error occurs while reading the catalog
    
    java.lang.NullPointerException - if base is null
  - Catalog
```
public Catalog(java.net.URL base,
               boolean allowCache,
               javax.swing.JProgressBar feedback)
        throws java.io.IOException
```
    Loads a catalog from a base URL. The URL of the catalog will be the base URL with "catalog.txt" appended. If feedback if non-null, then it will be updated with progress information.
    
    Parameters:
    
    base - the URL to load the catalog from
    
    allowCache - if true, and if the URL identifies the default catalog URL, then a cached version of the catalog may be returned
    
    feedback - an optional progress bar to send feedback to while reading
    
    Throws:
    
    java.io.IOException - if an error occurs while reading the catalog
    
    java.lang.NullPointerException - if base is null
- Method Detail
  - getLocalCopy
```
public static Catalog getLocalCopy()
```
    Returns the locally cached catalog, if any. If there is no locally cached catalog, returns null.
    
    Returns:
    
    the locally cached copy of the primary catalog, or null
  - getBaseURL
```
public final java.net.URL getBaseURL()
```
    Returns the base URL used to resolve the location of plug-in bundles listed in the catalog.
    
    Returns:
    
    the base URL to download plug-ins listed in the catalog from
  - setBaseURL
```
protected final void setBaseURL(java.net.URL url)
```
    Subclasses may use this to set a custom base URL.
    
    Parameters:
    
    url - the new base URL
  - size
```
public final int size()
```
    Returns the number of listings in the catalog, not counting any hidden listings. The first hidden listing, if any, begins at the index equal to this value.
    
    Returns:
    
    the number of non-hidden listings
  - trueSize
```
public final int trueSize()
```
    Returns the number of listings in the catalog, including any hidden listings. The number of hidden listings is always equal to trueSize() - size().
    
    Returns:
    
    the total number of listings, including hidden ones
  - get
```
public final Listing get(int n)
```
    Returns the listing at index n in the catalog.
    
    Parameters:
    
    n - the index of the desired listing
    
    Returns:
    
    the listing at the specified index
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - if the index is invalid
  - getVersioningState
```
public Catalog.VersioningState getVersioningState(int n)
```
    Compares the listing at index n with the set of installed plug-ins and returns a Catalog.VersioningState value that describes the relative version of the installed plug-in, if any.
    
    Parameters:
    
    n - the listing index to compare to installed plug-ins
    
    Returns:
    
    a comparison of the version of the plug-in in the listing and the installed version
  - setInstallFlag
```
public final void setInstallFlag(int n,
                                 boolean install)
```
    Mark the listing at index n for installation. All flagged plug-ins are installed together when installFlaggedPlugins() is called.
    
    Parameters:
    
    n - the index of the listing to mark
    
    install - the new value for the listing's install flag
  - getInstallFlag
```
public final boolean getInstallFlag(int n)
```
    Returns true if the listing at the indicated index is flagged for installation.
    
    Parameters:
    
    n - the index of the listing to test
    
    Returns:
    
    true if the listing is marked for installation
  - getInstallFlagCount
```
public final int getInstallFlagCount()
```
    Returns a count of the number of plug-ins that are currently flagged for installation from this catalog.
    
    Returns:
    
    the number of plug-ins that are flagged for installation
  - determineInstallationRequirements
```
public java.util.BitSet determineInstallationRequirements()
```
    Determines the installation requirements set for the plug-ins that are currently flagged for installation. The installation requirements set includes not just the plug-ins that are flagged for download, but any plug-ins that those plug-ins require (recursively). The requirements set is returned as a bit set in which the indexes of each possible listing are set to 0 if that listing would not be installed and 1 if it would.
    
    Returns:
    
    a set of the plug-ins that would be
  - installFlaggedPlugins
```
public boolean installFlaggedPlugins()
```
    Attempt to download and install all plug-ins that are currently flagged for installation. If a listing includes a requires entry, other plug-ins in the catalog that are named in the requires entry will be automatically flagged if they are not already flagged and they are not installed and up to date. This is recursive: if a required plug-in has required plugins, they are also added (and so on). When this method returns, all installation flags in this catalog will be cleared.
    
    Returns:
    
    true if a restart (of the application) is required to complete installation
  - isRestartRequiredAfterInstall
```
public boolean isRestartRequiredAfterInstall()
```
    Returns true if a restart (of the application) would be required after the currently selected plug-ins are installed. The answer is based on the types of plug-ins flagged for installation, and the types of any plug-ins they require.
    If this method returns false, a restart may still be required if one of the plug-in bundles could not be written and an autoupdate file was generated.
    
    Returns:
    
    true if a restart should not be required
  - findListingByUUID
```
public int findListingByUUID(java.util.UUID uuid)
```
    Returns the index of the listing in this catalog that has the requested UUID. If no listing matches the UUID, returns -1.
    
    Parameters:
    
    uuid - the unique ID to match
    
    Returns:
    
    the index of the plug-in with the requested UUID, or -1
  - reload
```
public void reload()
            throws java.io.IOException
```
    Reload the catalog from the source. This will clear all download flags. If an exception occurs, the original catalog and settings are retained.
    
    Throws:
    
    java.io.IOException - if an I/O exception occurs while reading the catalog
  - add
```
public void add(Listing li)
```
    Adds a listing to the catalog. If the version information for the listing indicates that the plug-in is too old for this version of the application, then the listing is not added.
    
    Parameters:
    
    li - the listing to add
    
    Throws:
    
    java.lang.IllegalArgumentException - if the listing has a catalog ID and another listing in the catalog uses the same UUID
  - remove
```
public boolean remove(java.util.UUID uuid)
```
    Removes the listing whose catalog ID matches the provided UUID.
    
    Parameters:
    
    uuid - the UUID of the listing to remove
    
    Returns:
    
    true if an entry was removed, false if no entry matches the UUID
  - write
```
public void write(java.io.OutputStream out)
           throws java.io.IOException
```
    Write the catalog to a stream as a catalog description file.
    
    Parameters:
    
    out - the stream to write to
    
    Throws:
    
    java.io.IOException - if an error occurs while writing the catalog
  - addPostInstallationHook
```
public static void addPostInstallationHook(java.lang.Runnable h)
```
    Adds a new post-installation hook. All current post-installation hooks are called after one or more new bundles are installed by calling installFlaggedPlugins(). This can be used to detect a previously missing plug-in bundle and change the behaviour of the application or plug-in accordingly. For example, when the core spelling bundle is missing, the application installs a hook that will activate spelling checking if the bundle is later installed.
    
    Parameters:
    
    h - the hook function to call following plug-in bundle installation
  - removePostInstallationHook
```
public static void removePostInstallationHook(java.lang.Runnable h)
```
    Removes a previously installed post-installation hook. It is safe to call this from within a hook (hooks can uninstall themselves).
    
    Parameters:
    
    h - the hook function to stop calling following plug-in bundle installation

Class Catalog

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Catalog

Catalog

Catalog

Catalog

Method Detail

getLocalCopy

getBaseURL

setBaseURL

size

trueSize

get

getVersioningState

setInstallFlag

getInstallFlag

getInstallFlagCount

determineInstallationRequirements

installFlaggedPlugins

isRestartRequiredAfterInstall

findListingByUUID

reload

add

remove

write

addPostInstallationHook

removePostInstallationHook