com.atlassian.gadgets.spi
Interface ExternalGadgetSpecStore

All Known Implementing Classes:

PluginSettingsExternalGadgetSpecStore

public interface ExternalGadgetSpecStore

Provides a means for storing, retrieving, and modifying a collection of external gadget spec URIs. Host applications that wish to allow administrators to add or remove gadgets should implement this interface.

Collection members are stored internally as ExternalGadgetSpecs. The implementation must create these members on demand when the add(java.net.URI) method is called.

Implementations should consider gadget spec URIs to be equal if they are semantically equivalent; formally, two gadget spec URIs are equal if the following is true:

firstURI.normalize().equals(secondURI.normalize());

Host applications that will not use the directory plugin do not need to implement this interface.

See Also:

ExternalGadgetSpec

Method Summary

ExternalGadgetSpec	add(URI gadgetSpecUri) Adds a gadget spec URI to this store and returns an ExternalGadgetSpec wrapper for it.
boolean	contains(URI gadgetSpecUri) Returns true if the URI is in the store, false otherwise.
Iterable<ExternalGadgetSpec>	entries() Retrieves all ExternalGadgetSpecs from the data store.
void	remove(ExternalGadgetSpecId externalGadgetSpecId) Removes the spec URI corresponding to the specified externalGadgetSpecId from the persistent data store.

Method Detail

entries

Iterable<ExternalGadgetSpec> entries()

Retrieves all ExternalGadgetSpecs from the data store. There is no guarantee that these will be sequenced in any particular order. This method must not return null; if the store is empty, it must return an Iterable with no contents.

Returns:

all of the ExternalGadgetSpecs in the store, returned in an unspecified order

Throws:

ExternalGadgetStoreException - if there is a problem when retrieving the ExternalGadgetSpecs from the persistent store

add

ExternalGadgetSpec add(URI gadgetSpecUri)

Adds a gadget spec URI to this store and returns an ExternalGadgetSpec wrapper for it. The store must not allow duplicate entries to be stored; if the gadget spec URI is already contained in this store, this method should return the existing ExternalGadgetSpec for it.

The implementation must consider syntactically different but semantically equivalent URIs to be equal for the purposes of duplicate elimination; specifically, the implementation is responsible for calling URI.normalize() on gadgetSpecUri before storing it.

Parameters:

gadgetSpecUri - the gadget spec URI to store. Must not be null.

Returns:

an ExternalGadgetSpec object wrapping the specified gadget spec URI

Throws:

ExternalGadgetStoreException - if there is a problem when adding the gadget spec URI to the persistent data store

NullPointerException - if gadgetSpecUri is null

remove

void remove(ExternalGadgetSpecId externalGadgetSpecId)

Removes the spec URI corresponding to the specified externalGadgetSpecId from the persistent data store. If externalGadgetSpecId does not correspond to any stored gadget spec URI, this method should do nothing but return.

Parameters:

externalGadgetSpecId - the gadget spec ID to be removed from the persistent data store. Must not be null.

Throws:

ExternalGadgetStoreException - thrown if there is a problem when removing the gadget from the persistent data store

NullPointerException - if externalGadgetSpecId is null

contains

boolean contains(URI gadgetSpecUri)

Returns true if the URI is in the store, false otherwise.

Parameters:

gadgetSpecUri - URI to check is in the store

Returns:

true if the URI is in the store, false otherwise