org.valkyriercp.command.CommandRegistry Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of valkyrie-rcp-core Show documentation
There is a newer version: 1.3
package org.valkyriercp.command;

import org.valkyriercp.command.support.AbstractCommand;
import org.valkyriercp.command.support.ActionCommand;
import org.valkyriercp.command.support.CommandGroup;
import org.valkyriercp.command.support.CommandNotOfRequiredTypeException;

/**
 * A registry for command objects.
 *
 * 
 * The commands to be placed in the registry must have non-null identifiers available via their
 * {@link AbstractCommand#getId()} method, and this id is expected to be unique amongst all the
 * commands in the application. Generally speaking, this uniqueness will not be enforced by the
 * framework but will instead allow commands to be overwritten by others with the same id.
 * 
 *
 * 
 * Implementations may allow for the creation of hierarchical registries whereby a registry may have
 * a parent registry. In this case, if a registry does not contain a requested command it will
 * delegate to its parent to find the command. Commands in a child registry will override commands
 * with the same ID in any ancestor registries.
 * 
 *
 * @author Keith Donald
 * @author Kevin Stembridge
 *
 */
public interface CommandRegistry {

    /**
     * Returns true if the registry contains a command with the given identifier.
     *
     * @param commandId The ID of the command to search for.
     * @return true if the registry contains the command, false otherwise.
     *
     * @throws IllegalArgumentException if {@code commandId} is null.
     */
    boolean containsCommand(String commandId);

    /**
     * Retrieves from the registry the command with the given identifier.
     *
     * @param commandId The ID of the command to be retrieved.
     * @return The command with the given ID, or null if no such command could be found.
     *
     * @throws IllegalArgumentException if {@code commandId} is null.
     */
    Object getCommand(String commandId);

    /**
     * Retrieves from the registry the command with the given identifier. An exception is thrown
     * if the retrieved command is not assignable to the required type.
     *
     * @param commandId The identifier of the command to be retrieved. Must not be null.
     * @param requiredType The required type of the command with the given id.
     *
     * @return The command with the given id if it exists in the registry and is of the required type.
     *
     * @throws CommandNotOfRequiredTypeException if the retrieved command is not assignable to
     * the required type.
     */
    Object getCommand(String commandId, Class requiredType) throws CommandNotOfRequiredTypeException;

    /**
     * Returns the type of the command with the given identifier, if it is contained in the
     * registry.
     *
     * @param commandId The ID of the command whose type is to be returned. Must not be null.
     * @return The type of the command with the given ID, or null if no such command exists in
     * the registry.
     *
     * @throws IllegalArgumentException if {@code commandId} is null.
     */
    Class getType(String commandId);

    /**
     * Returns true if the command with the given identifier is assignable to the given type.
     *
     * @param commandId The ID of the command whose type will be checked. Must not be null.
     * @param targetType The type to be checked against the type of the command. Must not be null.
     * @return true if a command with the given ID exists in the registry and it is assignable to
     * the given target type, false otherwise.
     *
     * @throws IllegalArgumentException if either argument is null.
     */
    boolean isTypeMatch(String commandId, Class targetType);

    /**
     * Returns the {@link ActionCommand} that has the given id.
     *
     * @param commandId The id of the action command to be returned.
     * @return The action command with the given id, or null if no such command exists in the
     * registry.
     *
     * @throws IllegalArgumentException if {@code commandId} is null.
     * @throws CommandNotOfRequiredTypeException if there is a command with the given id in the
     * registry but it is not of type {@link ActionCommand}.
     *
     * @deprecated use {@link #getCommand(String, Class)} instead. You may choose to either catch
     * the {@link CommandNotOfRequiredTypeException} or call {@link #isTypeMatch(String, Class)} first.
     */
    ActionCommand getActionCommand(String commandId);

    /**
     * Returns the {@link CommandGroup} that has the given id.
     *
     * @param groupId The id of the command group to be returned.
     * @return The command group with the given id, or null if no such command group exists in the
     * registry.
     *
     * @throws IllegalArgumentException if {@code commandId} is null.
     * @throws CommandNotOfRequiredTypeException if there is a command with the given id in the
     * registry but it is not of type {@link CommandGroup}.
     *
     * @deprecated use {@link #getCommand(String, Class)} instead. You may choose to either catch
     * the {@link CommandNotOfRequiredTypeException} or call {@link #isTypeMatch(String, Class)} first.
     */
    CommandGroup getCommandGroup(String groupId);

    /**
     * Returns true if the registry contains a command of type {@link ActionCommand} with the
     * given id.
     *
     * @param commandId The id of the command to be searched for.
     * @return true if the registry contains the command and it is assignable to {@link ActionCommand}.
     *
     * @deprecated Replaced by {@link #isTypeMatch(String, Class)}
     */
    boolean containsActionCommand(String commandId);

    /**
     * Returns true if the registry contains a command of type {@link CommandGroup} with the
     * given id.
     *
     * @param groupId The id of the command group to be searched for.
     * @return true if the registry contains the command and it is assignable to {@link CommandGroup}.
     *
     * @deprecated Replaced by {@link #isTypeMatch(String, Class)}
     */
    boolean containsCommandGroup(String groupId);

    /**
     * Registers the given command with the registry. Neither the command nor its id can be null.
     * All registered listeners will be notified of the newly registered command via their
     * {@link CommandRegistryListener#commandRegistered(CommandRegistryEvent)} method. If the
     * given command is an instance of {@link CommandGroup}, its
     * {@link CommandGroup#setCommandRegistry(CommandRegistry)} method must be called to set this
     * instance as the registry for the command group.
     *
     * @param command The command to be registered. Must not be null.
     *
     * @throws IllegalArgumentException if {@code command} is null or if its id is null.
     */
    void registerCommand(AbstractCommand command);

    /**
     * Sets a command executor for the command with the given id. The actual type of the command
     * must be assignable to {@link org.valkyriercp.command.support.TargetableActionCommand}.
     *
     * @param targetableCommandId The id of the targetable command that will have its executor set.
     * Must not be null.
     * @param commandExecutor The command executor. May be null.
     *
     * @throws IllegalArgumentException if {@code targetableCommandId} is null.
     * @throws CommandNotOfRequiredTypeException if the command with the given id is not a
     * {@link org.valkyriercp.command.support.TargetableActionCommand}.
     */
    void setTargetableActionCommandExecutor(String targetableCommandId, ActionCommandExecutor commandExecutor);

    /**
     * Adds the given listener to the colleciton of listeners that will be notified of registry events.
     *
     * @param listener The listener to be added. Must not be null.
     */
    void addCommandRegistryListener(CommandRegistryListener listener);

    /**
     * Remove the given listener from the collection of listeners that will be notified of registry events.
     *
     * @param listener The listener to be removed.
     */
    void removeCommandRegistryListener(CommandRegistryListener listener);

}