Start page / Plug-In Development / Universal Extensions / Data Access / Data Access Plug-In

Data Access Plug-In

FirstSpirit Developer API Interface: de.espirit.firstspirit.client.plugin.dataaccess.DataAccessPlugin
Developer API documentation: DataAccessPlugin<D>

The data access plug-in class defines a data access plug-in for use in FirstSpirit. It advertises foundational information such as label and icon, creates a session builder which connects the plug-in to its core data access functionality, and optionally provides aspects which mark the data access plug-in usable within the report UIs provided by SiteArchitect and ContentCreator.

Code Example

public class MyDataAccessPlugin implements DataAccessPlugin<MyDataObject> {

private final DataAccessAspectMap _aspects;
private BaseContext _context;

public MyDataAccessPlugin() {
_aspects = new DataAccessAspectMap();

public void setUp(@NotNull final BaseContext context) {
_context = context;

_aspects.put(Reporting.TYPE, new MyReportingAspect(_context));

public <A> A getAspect(@NotNull final DataAccessAspectType<A> type) {
return _aspects.get(type);

public String getLabel() {
return "My Data Access Plug-In";

public Image<?> getIcon() {
if (_context != null) {
final ImageAgent imageAgent = _context.requireSpecialist(ImageAgent.TYPE);
if ( {
return imageAgent.getImageFromUrl("path/to/myDataAccessPlugin.png");
} else {
return imageAgent.getImageFromIcon(new ImageIcon(getClass().getResource("myDataAccessPlugin.png")));
return null;

public DataAccessSessionBuilder<MyDataObject> createSessionBuilder() {
return new MyDataAccessSessionBuilder();

public void tearDown() {

public static class MyReportingAspect implements Reporting {

private final BaseContext _context;

public MyReportingAspect(@NotNull final BaseContext context) {
_context = context;

public Image<?> getReportIcon(final boolean active) {
final String activityFlag = active ? "active" : "inactive";
final ImageAgent imageAgent = _context.requireSpecialist(ImageAgent.TYPE);
if ( {
return imageAgent.getImageFromUrl("path/to/myDataAccessPluginReport_" + activityFlag + ".png");
} else {
return imageAgent.getImageFromIcon(
new ImageIcon(getClass().getResource("myDataAccessPluginReport" + activityFlag + ".png"))

Providing Aspects

FirstSpirit occasionally calls the method getAspect(...) with various aspect types as a parameter to identify which input components support a given aspect. If the data access plug-in class supports the requested aspect, the method should return an object which implements that aspect; otherwise, it should return null.

Data Access Plug-In Aspects




Methods / Notes


Specifies that the data access plug-in should be shown as a report in SiteArchitect and ContentCreator and provides a fitting icon.

Image<?> getReportIcon(boolean)
provides a client-specific icon (ContentCreator: Image<String>, SiteArchitect: Image<Icon>) which will be shown in the client's report bar.


Provides interactive items which operate on individual report entries.

ReportItem<D> getClickItem()
may return a report item which is activated by clicking on a report entry's snippet.

Collection<? extends ReportItem<D>> getItems()
provides an arbitrary number of report items which are shown as buttons near report entries.

Report items may implement any of the following interfaces:




Provides interactive items which operate within the context of the entire report (i.e. without association with individual report entries).

Collection<? extends Item<BaseContext>> getStaticItems()
provides an arbitrary number of interactive items which are made available for interaction in the report's header.

A static item class must implement the interface Item<BaseContext> as well as one of the following interfaces:




Provides access control for data displayed by a data access plugin.

This aspect may be used to implement authorization for access to data as well as authentication and authorization against web services from which this data is sourced. In various contexts, this may include interactive communication with the user (e.g. displaying a login form).

void verifyAccess() throws AccessDeniedException
verifies if the current data access session's data is accessible within the current user session and execution environment.

void requireAccess(@NotNull BaseContext context)
throws AccessDeniedException

attempts to establish accessibility of the data access session's data, e.g. login (authentication and authorization), for the current user session and execution environment.

The BaseContext object provided as a parameter indicates the current execution environment, some of which are fit for interaction with the user, e.g. displaying a login form:

  • WEBEDIT execution in ContentCreator (interaction possible)
  • ARCHITECT execution in SiteArchitect (interaction possible)
  • MANAGER execution in ServerManager (interaction possible)
  • GENERATION execution during a generation run
  • FORM execution within an input component (e.g. FS_INDEX)
  • REPORT execution within a report
  • HEADLESS execution in a headless environment (precludes interaction, regardless of which other environments are indicated)

Several other environments are available as well but are not listed as they are not relevant to this data access plugin aspect. See Information About the Execution Environment (ODFS) and BaseContext (FirstSpirit API Documentation) for more information.

@Nullable String getAcquireAccessLabel()
provides a brief text that is used to label the action “Request access” that is shown in the user interface if access is currently not granted.

If access permission is granted, it is only valid for that particular context, e.g., only for the report or the input component. This should be taken into account when implementing the plugin. If access control is required for displaying content in the preview, this must also be taken into account in the implementation of the plugin itself.


Aspect providing means to determine and report references via the “DataAccess-Plugin”. There are two categories of references which both require a distinct method.

The interface also serves as an adapter, so only the (empty) method required by the “DataAccess-Plugin” needs to be implemented. There are two methods available:

  • void reportValueReferences(ValueReferencesJournal journal, Set<String> identifiers)
    is used for references of the values selected / saved in the “DataAccess-Plugin” by the editor, e.g. FirstSpirit objects, external elements. Objects for which references are reported are identified by a unique identifier.
  • void reportModelReferences(ModelReferencesJournal journal)
    is used for references to FirstSpirit objects that emerge from the configuration of the “DataAccess-Plugin”, e.g. FirstSpirit templates.

This interface is available for reporting references to values, and provides several methods for reporting different object types or for reporting defective references.

  • void addBrokenReferenceToDataset(Schema schema, String entityTypeName, UUID gid)
    Adds a reference to a FirstSpirit Dataset to this journal, where the referenced dataset could not be found (e.g., may be deleted from the project).
  • void addBrokenReferenceToElement(String uid, IDProvider.UidType uidType, String remote)
    Adds a reference to a FirstSpirit element to this journal, where the actual referenced element could not be found (e.g., may be deleted from the project).
  • void addReferenceToElement(IDProvider element)
    Adds a reference to a FirstSpirit element to this journal.
  • void addReferenceToExternal(String category, String reference)
    Adds a reference to an external element to this journal.

This interface is available for reporting references to FirstSpirit objects resulting from the configuration of the “DataAccess-Plugin” (e.g. FirstSpirit templates or media).

  • void addModelElement(IDProvider element)
    Adds the given FirstSpirit element as model reference to this journal.


© 2005 - 2024 Crownpeak Technology GmbH | All rights reserved. | FirstSpirit 2024.7 | Data privacy