Details

    • Type: Improvement Improvement
    • Status: Resolved
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: current
    • Fix Version/s: milestone 1
    • Component/s: api
    • Labels:
      None
    • Environment:

      Operating System: All
      Platform: All

    • Issuezilla Id:
      13

      Description

      janne.jalkanen@ecyrd.com proposes in an email:


      [...]
      Repository lifecycle management would be useful - if apps are embedding JCR containers, there's no clear
      way to for example tell them to reload the configuration or restart (or even shutdown cleanly). I know it's
      useless if you're connecting elsewhere, but it would be nice to be at least to hint. For example through a
      RepositoryManagement interface or a set of standard JMX calls...
      [...]

        Activity

        Hide
        rhauch added a comment - - edited

        I think we've met in the middle. Here's my understanding of what we've settled upon, and please correct me if I'm mistaken. The first is the new 'RepositoryManager' interface:

        /**

        • A <code>RepositoryManager</code> object represents a management view of the Session's Repository instance.
        • This is useful for applications that embed a JCR repository and need a way to manage the lifecycle of that
        • Repository instance. Each <code>RepositoryManager</code> object is associated one-to-one with a
        • <code>Session</code> object and is defined by the authorization settings of that session object.
        • <p>
        • The <code>RepositoryManager</code> object can be acquired using a {@link Session}

          by calling

        • <code>Session.getWorkspace().getRepositoryManager()</code> on a session object, and the
        • Likewise, the Repository being managed can be found for a given RepositoryManager object by calling
        • <code>mgr.getWorkspace().getSession().getRepository()</code>.
        • </p>
        • @since 2.1
          */
          public interface RepositoryManager {
          /**
        • Return the <code>Workspace</code> object through which this repository manager was created.
        • @return the {@ Workspace}

          object.
          */
          Workspace getWorkspace();

        /**

        • Closes the <code>Repository</code> by preventing the creation of new sessions
        • and freeing all resources. The <code>immediate</code> parameter dictates whether existing
        • sessions should be closed immediately or allowed to close naturally.
        • Either way, this method always blocks until all sessions are closed and the repository has
        • completely terminated.
        • <p>
        • Some repository implementations may not allow repositories to be closed, while other
        • implementations might allow closing only for certain configurations (e.g., repositories
        • embedded within an application). An implementation will throw an
        • {@link UnsupportedRepositoryException}

          if the particular repository cannot be closed,

        • or an {@link AccessDeniedException}

          when the repository can be closed but the session does

        • not have the authority to do so.
        • </p>
        • @param closeSessionsImmediately true if all existing sessions should be closed immediately,
        • or false if they are to be allowed to close naturally.
        • @throws AccessDeniedException if the caller does not have authorization to close the repository.
        • @throws UnsupportedRepositoryException if the repository implementation does not support
        • or allow the repository to be closed.
        • @throws RepositoryException if an error occurred while shutting down the repository.
          */
          void closeRepository( boolean closeSessionsImmediately )
          throws AccessDeniedException, UnsupportedRepositoryException, RepositoryException;
          }

        And to the existing "Workspace" interface we add the following method to return a RepositoryManager instance:

        public interface Workspace {
        ...

        /**

        • Return a RepositoryManager that can be used to administer the Repository instance through
        • which this workspace's session was acquired.
        • @return the {@link RepositoryManager}

          instance.

        • @throws AccessDeniedException if the caller does not have authorization to obtain the manager.
        • @throws RepositoryException if another error occurred.
        • @since 2.1
          */
          RepositoryManager getRepositoryManager()
          throws AccessDeniedException, RepositoryException;

        ...
        }

        As much as I'd think there should be a "RepositoryManager.getRepository()" method, that's not the pattern of the JSR-283 interfaces. I think it's more important to be consistent, so I left such a method out of the proposal.

        Show
        rhauch added a comment - - edited I think we've met in the middle. Here's my understanding of what we've settled upon, and please correct me if I'm mistaken. The first is the new 'RepositoryManager' interface: /** A <code>RepositoryManager</code> object represents a management view of the Session's Repository instance. This is useful for applications that embed a JCR repository and need a way to manage the lifecycle of that Repository instance. Each <code>RepositoryManager</code> object is associated one-to-one with a <code>Session</code> object and is defined by the authorization settings of that session object. <p> The <code>RepositoryManager</code> object can be acquired using a {@link Session} by calling <code>Session.getWorkspace().getRepositoryManager()</code> on a session object, and the Likewise, the Repository being managed can be found for a given RepositoryManager object by calling <code>mgr.getWorkspace().getSession().getRepository()</code>. </p> @since 2.1 */ public interface RepositoryManager { /** Return the <code>Workspace</code> object through which this repository manager was created. @return the {@ Workspace} object. */ Workspace getWorkspace(); /** Closes the <code>Repository</code> by preventing the creation of new sessions and freeing all resources. The <code>immediate</code> parameter dictates whether existing sessions should be closed immediately or allowed to close naturally. Either way, this method always blocks until all sessions are closed and the repository has completely terminated. <p> Some repository implementations may not allow repositories to be closed, while other implementations might allow closing only for certain configurations (e.g., repositories embedded within an application). An implementation will throw an {@link UnsupportedRepositoryException} if the particular repository cannot be closed, or an {@link AccessDeniedException} when the repository can be closed but the session does not have the authority to do so. </p> @param closeSessionsImmediately true if all existing sessions should be closed immediately, or false if they are to be allowed to close naturally. @throws AccessDeniedException if the caller does not have authorization to close the repository. @throws UnsupportedRepositoryException if the repository implementation does not support or allow the repository to be closed. @throws RepositoryException if an error occurred while shutting down the repository. */ void closeRepository( boolean closeSessionsImmediately ) throws AccessDeniedException, UnsupportedRepositoryException, RepositoryException; } And to the existing "Workspace" interface we add the following method to return a RepositoryManager instance: public interface Workspace { ... /** Return a RepositoryManager that can be used to administer the Repository instance through which this workspace's session was acquired. @return the {@link RepositoryManager} instance. @throws AccessDeniedException if the caller does not have authorization to obtain the manager. @throws RepositoryException if another error occurred. @since 2.1 */ RepositoryManager getRepositoryManager() throws AccessDeniedException, RepositoryException; ... } As much as I'd think there should be a "RepositoryManager.getRepository()" method, that's not the pattern of the JSR-283 interfaces. I think it's more important to be consistent, so I left such a method out of the proposal.
        Hide
        Peeter Piegaze added a comment -

        Stefan, what do you think of this latest proposal?

        Show
        Peeter Piegaze added a comment - Stefan, what do you think of this latest proposal?
        Hide
        stefan_guggisberg added a comment -

        i'm fine with randall's latest proposal. i have one minor suggestion however,
        i think we should add language that implementations may not support/allow
        closing the repository method for various reasons. maybe we should
        explicitly add UnsupportedRepositoryException to the throws clause.

        Show
        stefan_guggisberg added a comment - i'm fine with randall's latest proposal. i have one minor suggestion however, i think we should add language that implementations may not support/allow closing the repository method for various reasons. maybe we should explicitly add UnsupportedRepositoryException to the throws clause.
        Hide
        rhauch added a comment - - edited

        I agree with Stefan's suggestion on the language to add, and am good with adding the exception to the throws clause for 'closeRepository()'. I've update the proposed code above, but I'd be happy to hear of alternative suggestions for any of the wording in the JavaDoc.

        Show
        rhauch added a comment - - edited I agree with Stefan's suggestion on the language to add, and am good with adding the exception to the throws clause for 'closeRepository()'. I've update the proposed code above, but I'd be happy to hear of alternative suggestions for any of the wording in the JavaDoc.
        Hide
        Peeter Piegaze added a comment -

        Fixed as per Randall's latest updated proposal

        Show
        Peeter Piegaze added a comment - Fixed as per Randall's latest updated proposal

          People

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

            Dates

            • Created:
              Updated:
              Resolved: