jsr-333
  1. jsr-333
  2. JSR_333-26

Simplify ObservationManager.addEventListener

    Details

    • Type: Improvement Improvement
    • Status: Resolved
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: api
    • Labels:
      None

      Description

      The method takes 7 parameters, which is not very user friendly:

      ObservationManager.addEventListener(EventListener listener, int eventTypes, java.lang.String absPath, boolean isDeep, java.lang.String[] uuid, java.lang.String[] nodeTypeName, boolean noLocal)

      An alternative would be to use the builder pattern:

      EventFilter filter = observationManager.createEventFilter().setEventTypes(eventTypes).setAbsPath(absPath).
      setDeep(isDeep).setIdentifiers(uuids).setNodeTypes(nodeTypeName).setNoLocal(noLocal);
      observationManager.addEventListener(listener, filter);

      The EventFilter could also be used for ObservationManager.getEventJournal(EventFilter filter).

      Those are the only two methods I propose to add.

      Just for reference, other methods with many parameter:

      5:

      ObservationManager.getEventJournal(int eventTypes, java.lang.String absPath, boolean isDeep, java.lang.String[] uuid, java.lang.String[] nodeTypeName)

      LockManager.lock(java.lang.String absPath, boolean isDeep, boolean isSessionScoped, long timeoutHint, java.lang.String ownerInfo)

      4:

      Session.exportDocumentView(java.lang.String absPath, org.xml.sax.ContentHandler contentHandler, boolean skipBinary, boolean noRecurse)

      Session.exportDocumentView(java.lang.String absPath, java.io.OutputStream out, boolean skipBinary, boolean noRecurse)

      Session.exportSystemView(java.lang.String absPath, org.xml.sax.ContentHandler contentHandler, boolean skipBinary, boolean noRecurse)

      Session.exportSystemView(java.lang.String absPath, java.io.OutputStream out, boolean skipBinary, boolean noRecurse)

      VersionManager.merge(java.lang.String absPath, java.lang.String srcWorkspace, boolean bestEffort, boolean isShallow)

      Workspace.clone(java.lang.String srcWorkspace, java.lang.String srcAbsPath, java.lang.String destAbsPath, boolean removeExisting)

        Issue Links

          Activity

          Hide
          Peeter Piegaze added a comment -

          This issue falls under the ease-of-use category that we established as a goal of JCR 2.1

          Show
          Peeter Piegaze added a comment - This issue falls under the ease-of-use category that we established as a goal of JCR 2.1
          Hide
          Peeter Piegaze added a comment -

          Proposal: Add the following methods to Observation Manager and add the following new Interface, EventFilter:

          public interface ObservationManager {

          /**

          • Adds an <code>EventListener</code> with the characteristics as specified in the passed <code>EventFilter</code>.
          • Has the same effect as {@link #addEventListener(EventListener listener, int eventTypes, String absPath, boolean isDeep, String[] uuid, String[] nodeTypeName, boolean noLocal)}

            .
            *

          • @param listener an {@link EventListener}

            object.

          • @param filter an {@link EventFilter} object.
            * @throws RepositoryException If an error occurs.
            */
            public void addEventListener(EventListener listener, EventFilter filter) throws RepositoryException;

            /**
            * Retrieves the event journal for this workspace filtered by the passed <code>EventFilter</code>.
            * This method behaves the same as {@link #getEventJournal(int eventTypes, String absPath, boolean isDeep, String[] uuid, String[] nodeTypeName)}.
            * @param filter an {@link EventFilter}

            object.

          • @throws RepositoryException If an error occurs.
            */
            public void getEventJournal(EventFilter filter) throws RepositoryException;

          /**

          • Creates an {@link EventFilter}

            that can then be configured and passed to the method

            {@link #addEventListener}

            .
            *

          • @return an <code>EventFilter</code>.
            */
            public EventFilter createEventFilter();

          }

          /**

          • An EventFilter object.
          • <p>
          • A storage object for event filter configuration. A blank EventFilter is
          • acquired through {@link ObservationManager#createEventFilter()}

            .

          • The parameters of the filter can then be set by chaining the set methods,
          • since each method returns the same EventFilter with indicated parameter set.
          • <p>
          • Note that since each method returns the same EventFilter with appropriate parameter set,
          • the set methods can be chained.
            */
            public interface EventFilter {

          /**

          • Sets the <code>eventTypes</code> parameter of the filter.
          • See {@link ObservationManager#addEventListener} for information on this parameter.
            * If left unset, this parameter defaults to <code>null</code>.
            * @param eventTypes an <code>int</code>.
            * @return This EventListener object with the <code>eventTypes</code> parameter set.
            */
            public EventFilter setEventTypes(int eventTypes);

            /**
            * Sets the <code>absPath</code> parameter of the filter.
            * See {@link ObservationManager#addEventListener}

            for information on this parameter.

          • If left unset, this parameter defaults to <code>null</code>.
          • @param absPath an absolute path <code>String</code>.
          • @return This EventListener object with the <code>absPath</code> parameter set.
            */
            public EventFilter setAbsPath(String absPath);

          /**

          • Sets the <code>isDeep</code> parameter of the filter.
          • See {@link ObservationManager#addEventListener} for information on this parameter.
            * If left unset, this parameter defaults to <code>false</code>.
            * @param isDeep a <code>boolean</code>.
            * @return This EventListener object with the <code>isDeep</code> parameter set.
            */
            public EventFilter setDeep(boolean isDeep);

            /**
            * Sets the <code>uuids</code> parameter of the filter.
            * See {@link ObservationManager#addEventListener}

            for information on this parameter.

          • If left unset, this parameter defaults to <code>null</code>.
          • @param uuids a <code>String</code> array.
          • @return This EventListener object with the <code>uuids</code> parameter set.
            */
            public EventFilter setIdentifiers(String[] uuids);

          /**

          • Sets the <code>nodeTypeName</code> parameter of the filter.
          • See {@link ObservationManager#addEventListener} for information on this parameter.
            * If left unset, this parameter defaults to <code>null</code>.
            * @param nodeTypeName a <code>String</code> array.
            * @return This EventListener object with the <code>nodeTypeName</code> parameter set.
            */
            public EventFilter setNodeTypes(String[] nodeTypeName);

            /**
            * Sets the <code>noLocal</code> paremeter of the filter.
            * See {@link ObservationManager#addEventListener}

            for infomration on this parameter.

          • If left unset, this parameter defaults to <code>false</code>.
          • @param noLocal a <code>boolean</code>.
          • @return This EventListener object with the <code>noLocal</code> parameter set.
            */
            public EventFilter setNoLocal(boolean noLocal);
            }
          Show
          Peeter Piegaze added a comment - Proposal: Add the following methods to Observation Manager and add the following new Interface, EventFilter: public interface ObservationManager { /** Adds an <code>EventListener</code> with the characteristics as specified in the passed <code>EventFilter</code>. Has the same effect as {@link #addEventListener(EventListener listener, int eventTypes, String absPath, boolean isDeep, String[] uuid, String[] nodeTypeName, boolean noLocal)} . * @param listener an {@link EventListener} object. @param filter an {@link EventFilter} object. * @throws RepositoryException If an error occurs. */ public void addEventListener(EventListener listener, EventFilter filter) throws RepositoryException; /** * Retrieves the event journal for this workspace filtered by the passed <code>EventFilter</code>. * This method behaves the same as {@link #getEventJournal(int eventTypes, String absPath, boolean isDeep, String[] uuid, String[] nodeTypeName)}. * @param filter an {@link EventFilter} object. @throws RepositoryException If an error occurs. */ public void getEventJournal(EventFilter filter) throws RepositoryException; /** Creates an {@link EventFilter} that can then be configured and passed to the method {@link #addEventListener} . * @return an <code>EventFilter</code>. */ public EventFilter createEventFilter(); } /** An EventFilter object. <p> A storage object for event filter configuration. A blank EventFilter is acquired through {@link ObservationManager#createEventFilter()} . The parameters of the filter can then be set by chaining the set methods, since each method returns the same EventFilter with indicated parameter set. <p> Note that since each method returns the same EventFilter with appropriate parameter set, the set methods can be chained. */ public interface EventFilter { /** Sets the <code>eventTypes</code> parameter of the filter. See {@link ObservationManager#addEventListener} for information on this parameter. * If left unset, this parameter defaults to <code>null</code>. * @param eventTypes an <code>int</code>. * @return This EventListener object with the <code>eventTypes</code> parameter set. */ public EventFilter setEventTypes(int eventTypes); /** * Sets the <code>absPath</code> parameter of the filter. * See {@link ObservationManager#addEventListener} for information on this parameter. If left unset, this parameter defaults to <code>null</code>. @param absPath an absolute path <code>String</code>. @return This EventListener object with the <code>absPath</code> parameter set. */ public EventFilter setAbsPath(String absPath); /** Sets the <code>isDeep</code> parameter of the filter. See {@link ObservationManager#addEventListener} for information on this parameter. * If left unset, this parameter defaults to <code>false</code>. * @param isDeep a <code>boolean</code>. * @return This EventListener object with the <code>isDeep</code> parameter set. */ public EventFilter setDeep(boolean isDeep); /** * Sets the <code>uuids</code> parameter of the filter. * See {@link ObservationManager#addEventListener} for information on this parameter. If left unset, this parameter defaults to <code>null</code>. @param uuids a <code>String</code> array. @return This EventListener object with the <code>uuids</code> parameter set. */ public EventFilter setIdentifiers(String[] uuids); /** Sets the <code>nodeTypeName</code> parameter of the filter. See {@link ObservationManager#addEventListener} for information on this parameter. * If left unset, this parameter defaults to <code>null</code>. * @param nodeTypeName a <code>String</code> array. * @return This EventListener object with the <code>nodeTypeName</code> parameter set. */ public EventFilter setNodeTypes(String[] nodeTypeName); /** * Sets the <code>noLocal</code> paremeter of the filter. * See {@link ObservationManager#addEventListener} for infomration on this parameter. If left unset, this parameter defaults to <code>false</code>. @param noLocal a <code>boolean</code>. @return This EventListener object with the <code>noLocal</code> parameter set. */ public EventFilter setNoLocal(boolean noLocal); }
          Hide
          Peeter Piegaze added a comment -

          As for the other methods with many params, I suggest that we could create a similar LockParam interface for the final 4 parameters of the lock method (apart from the path).

          For the other examples given (the four param ones), I think we should just leave them as is.

          Show
          Peeter Piegaze added a comment - As for the other methods with many params, I suggest that we could create a similar LockParam interface for the final 4 parameters of the lock method (apart from the path). For the other examples given (the four param ones), I think we should just leave them as is.
          Hide
          thomasmueller2 added a comment -

          I think this is a very good solution. Should the EventFilter class also contain the getter methods?

          Show
          thomasmueller2 added a comment - I think this is a very good solution. Should the EventFilter class also contain the getter methods?
          Hide
          Peeter Piegaze added a comment -

          fixed.

          Show
          Peeter Piegaze added a comment - fixed.

            People

            • Assignee:
              Unassigned
              Reporter:
              thomasmueller2
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: