Package com.orchestranetworks.userservice

Interface UserService<S extends EntitySelection>

  • Type Parameters:
    S - the nature of the service, namely the type of the selection on which it works.
    All Known Subinterfaces:
    UserServiceExtended<S>, UserServiceForCreate<S>
    public interface UserService<S extends EntitySelection>
    Main interface to be implemented for a user service.

    Declaration

    A user service must be declared in a module or a data model. Declaring a user service requires implementing the interface UserServiceDeclaration.

    Life cycle

    • When the first request is received:
      1. the user service class is instantiated using the method UserServiceDeclaration.createUserService();
      2. if the user service implements interface UserServiceExtended, method UserServiceExtended.initialize() will be called. this method may interrupt user service startup.
      3. If previous method is not implemented or if it does not interrupt startup, the page is displayed as described in the 'Display' section below.
    • When the following requests are received:
      1. if an event is associated with the request, it is processed as described in the 'Events' section below;
      2. if not, the page is displayed again as described in the 'Display' section below.

    Display

    To display a service, EBX® will call the following methods in the given sequence:

    1. setupObjectContext(…)
    2. setupDisplay(…)
    3. content.writePane(…) (content is set by methods setContent(UserServicePane) or setContent(UserServiceRawPane)).

    Events

    A user service can receive events. Events can be triggered by a button or a URL. There are three types of events:

    • a form submit event,
    • an action event,
    • a revert event.

    A submit event is an EBX® form submit. Submitted data is validated first by EBX®, then at the service-level by invoking the method validate(…). If data is not valid, the user service is redisplayed (see previous 'Display' section). If data is valid, the previously registered callback for the event is called.

    An action event can be triggered by a URL or a button. No data is submitted and the previously registered callback for the event is always called.

    Before returning to EBX® the outcome of the event (an object implementing interface UserServiceEventOutcome), the method processEventOutcome(…) is called, giving the opportunity to the user service to process the result and possibly change the value.

    If no callback is found for the event or the callback returns null, the method processEventOutcome(…) is not called and the user service is redisplayed.

    A revert event can be triggered by a URL or a button. It is a special type of event that restarts the service. The current class instance is deleted and a new one is created. No callback is called.

    Multi-threading

    An instance of a class that implements this interface may live during more than a HTTP single request but EBX® guarantees that only one HTTP request at a time will access it. Therefore it does not need to be thread safe.

    Since:
    5.8.0

    • Method Detail

      • setupObjectContext

        void setupObjectContext​(UserServiceSetupObjectContext<S> aContext,
                        UserServiceObjectContextBuilder aBuilder)
        This method can define objects or remove objects managed by the user service. It is called once for each HTTP request.
        Parameters:
        aContext - provides information about the current context.
        aBuilder - provides methods to define or remove objects.

      • setupDisplay

        void setupDisplay​(UserServiceSetupDisplayContext<S> aContext,
                  UserServiceDisplayConfigurator aConfigurator)
        This method configures the user service display. It can setup the header, the bottom buttons and the content callback.

        By default, the user service displays a header with the label specified by the user service declaration and no buttons.

        Parameters:
        aContext - provides information about the current context.
        aConfigurator - allows configuring the display.

      • validate

        void validate​(UserServiceValidateContext<S> aContext)
        This method offers the opportunity to perform custom validation on a form submit. It can add error messages.

        It is called after all components have been validated (built-in and UI bean alike).

        If any component or this method adds an error, the event is aborted (not processed) and the user service is redisplayed.

        Parameters:
        aContext - provides information about the current context.

      • processEventOutcome

        UserServiceEventOutcome processEventOutcome​(UserServiceProcessEventOutcomeContext<S> aContext,
                                            UserServiceEventOutcome anEventOutcome)
        This method is called by EBX® after processing initialization or an action or submit event callback if the returned a not null value.

        This allows callbacks to return values that can trigger specific actions by this method.

        If all callbacks return only standard outcomes (outcomes created by UserServiceNext), a simple implementation of this method can always return the parameter anEventOutcome.

        Parameters:
        aContext - the event context.
        anEventOutcome - the event callback outcome.
        Returns:
        A value returned by a method of class UserServiceNext, if null or an invalid value, the user service is redisplayed.