Accessing FirstSpirit Functionality

Within its APIs, FirstSpirit functionality is separated into individual, subject-specific groups that provide centralized access to FirstSpirit objects. This allows for development of FirstSpirit plug-ins that can interact with both ContentCreator and SiteArchitect user interfaces in general use cases, while implementing client-specific functionality elsewhere.

Agents

The functionally separated and modularized FirstSpirit API can be accessed by agents, which either provide information items about a specific subject directly or defer to other objects that implement API functionality.

Each agent provides functionality geared towards a certain subject area, e.g., the OperationAgent allows performance of various dialog and message displays. Agents may be project-independent or bound to a specific project.

Depending on the programmatic context, different agents are available. A list of agents is available in the FirstSpirit Developer API documentation for the class SpecialistType; see Uses for a list of implementing classes which represent individual agents.

With few exceptions, these agents may be accessed in both ContentCreator and SiteArchitect-specific plug-ins.

Obtaining Agents

Agents are always procured by requesting or requiring it from a SpecialistsBroker. All context interfaces (e.g. BaseContext and plug-in-specific context objects such as ToolbarContext) used in the FirstSpirit APIs' client plug-in interfaces are extensions of this interface.

Context objects based on the SpecialistsBroker interface provide the following methods:

• <S> S requestSpecialist(SpecialistType<S> type)
  Returns the requested agent if available. May return null if the agent is not available.
• <S> S requireSpecialist(SpecialistType<S> type) throws IllegalStateException
  Likewise, this method returns an agent if available. An exception is thrown if the requested agent is not available.

The SpecialistType required as a parameter to these methods is generally provided as a constant of the agent interface, such as AgentInterfaceName.TYPE. A specific agent may be procured as such:

public void example(BaseContext context) {
    StoreAgent myStoreAgent = context.requestSpecialist(StoreAgent.TYPE);
    if (myStoreAgent != null) {
        // Use the agent.
    }
}

In this example, a StoreAgent object is merely requested but not required. While additional code is required to properly handle situations in which the requested agent may not be available, use of requestSpecialist is ideally suited for functionality that may continue to execute regardless of if an agent is available.

Functionality that absolutely requires an agent to be present should use requireSpecialist and handle exceptions accordingly.