jsr-333
  1. jsr-333
  2. JSR_333-46

Add support for registering node types defined in CND file

    Details

    • Type: New Feature New Feature
    • Status: Resolved
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: api, spec
    • Labels:
      None

      Description

      There is no way to use the standard JCR 2.0 (JSR-283) API to load node type definitions from a CND file, even though the CND file format was standardized as part of JSR-283. Instead, implementation-specific techniques or non-standard utilities must be used to parse the CND file into NodeTypeDefinition instances, and then the current NodeTypeManager.registerNodeTypes(NodeTypeDefinition[], boolean) method must be called.

      I propose that one three new method be added to NodeTypeManager to enable JCR clients to use the standard JCR 2.1 API to register the node type definitions within one or more CND files. The three new methods is are similar to the registerNodeTypes(NodeTypeDefinition[] ntds, boolean allowUpdate) method that existed in JCR 2.0, except that it has as the first parameter an InputStream containing the CND content. and the three new method vary only in the first parameter that defines the CND content: by InputStream, by java.net.URL, and by java.io.File.

      The benefit for developers of JCR client applications is clear and substantial. On the other hand, the cost to implementers is likely minimal, since JCR 2.0 implementations likely can already read the CND files and create the NodeTypeDefinition instances, and they can implement the these new method by then delegating to the existing registerNodeTypes(NodeTypeDefinition[],boolean) method.

      /**
       * Registers or updates the node type definitions per the Compact Node Definition
       * (CND) file given by the supplied stream. This method is used to register 
       * or update a set of node types with mutual dependencies. Returns an iterator
       * over the resulting <code>NodeType</code> objects.
       * <p>
       * The effect of the method is "all or nothing"; if an error occurs, no node
       * types are registered or updated.
       * </p>
       *
       * @param stream the stream containing the node type definitions in CND format
       * @param allowUpdate a boolean stating whether existing node type definitions should be modified/updated
       * @return the registered node types.
       * @throws IOException if there is a problem reading from the supplied stream
       * @throws InvalidNodeTypeDefinitionException
       *                                 if a <code>NodeTypeDefinition</code>
       *                                 within the <code>Collection</code> is invalid or if the
       *                                 <code>Collection</code> contains an object of a type other than
       *                                 <code>NodeTypeDefinition</code>.
       * @throws NodeTypeExistsException if <code>allowUpdate</code> is
       *                                 <code>false</code> and a <code>NodeTypeDefinition</code> within the
       *                                 <code>Collection</code> specifies a node type name that is already
       *                                 registered.
       * @throws UnsupportedRepositoryOperationException
       *                                 if this implementation
       *                                 does not support node type registration.
       * @throws RepositoryException     if another error occurs.
       * @since JCR 2.1
       */
      NodeTypeIterator registerNodeTypes( InputStream stream,
                                          boolean allowUpdate )
          throws IOException, InvalidNodeTypeDefinitionException, NodeTypeExistsException, 
          UnsupportedRepositoryOperationException, RepositoryException;
      

      UPDATE BY RMH: Previously, two other methods were proposed, but comments/feedback suggested they were superfluous. So these methods are no longer proposed to be included in the API:

      /**
       * Registers or updates the node type definitions per the Compact Node Definition
       * (CND) file given by the supplied file. This method is used to register 
       * or update a set of node types with mutual dependencies. Returns an iterator
       * over the resulting <code>NodeType</code> objects.
       * <p>
       * The effect of the method is "all or nothing"; if an error occurs, no node
       * types are registered or updated.
       * </p>
       *
       * @param file the file containing the node types
       * @param allowUpdate a boolean stating whether existing node type definitions should be modified/updated
       * @return the registered node types.
       * @throws IOException if there is a problem reading from the supplied stream
       * @throws InvalidNodeTypeDefinitionException
       *                                 if a <code>NodeTypeDefinition</code>
       *                                 within the <code>Collection</code> is invalid or if the
       *                                 <code>Collection</code> contains an object of a type other than
       *                                 <code>NodeTypeDefinition</code>.
       * @throws NodeTypeExistsException if <code>allowUpdate</code> is
       *                                 <code>false</code> and a <code>NodeTypeDefinition</code> within the
       *                                 <code>Collection</code> specifies a node type name that is already
       *                                 registered.
       * @throws UnsupportedRepositoryOperationException
       *                                 if this implementation
       *                                 does not support node type registration.
       * @throws RepositoryException     if another error occurs.
       * @since JCR 2.1
       */
      NodeTypeIterator registerNodeTypes( File file,
                                          boolean allowUpdate ) 
          throws IOException, InvalidNodeTypeDefinitionException, NodeTypeExistsException, 
          UnsupportedRepositoryOperationException, RepositoryException;
      
      /**
       * Registers or updates the node type definitions per the Compact Node Definition
       * (CND) file given by the supplied URL. This method is used to register 
       * or update a set of node types with mutual dependencies. Returns an iterator
       * over the resulting <code>NodeType</code> objects.
       * <p>
       * The effect of the method is "all or nothing"; if an error occurs, no node
       * types are registered or updated.
       * </p>
       *
       * @param url the URL that can be resolved to the file containing the node type definitions in CND format
       * @param allowUpdate a boolean stating whether existing node type definitions should be modified/updated
       * @return the registered node types.
       * @throws IOException if there is a problem reading from the supplied stream
       * @throws InvalidNodeTypeDefinitionException
       *                                 if a <code>NodeTypeDefinition</code>
       *                                 within the <code>Collection</code> is invalid or if the
       *                                 <code>Collection</code> contains an object of a type other than
       *                                 <code>NodeTypeDefinition</code>.
       * @throws NodeTypeExistsException if <code>allowUpdate</code> is
       *                                 <code>false</code> and a <code>NodeTypeDefinition</code> within the
       *                                 <code>Collection</code> specifies a node type name that is already
       *                                 registered.
       * @throws UnsupportedRepositoryOperationException
       *                                 if this implementation
       *                                 does not support node type registration.
       * @throws RepositoryException     if another error occurs.
       * @since JCR 2.1
       */
      NodeTypeIterator registerNodeTypes( URL url,
                                          boolean allowUpdate ) 
          throws IOException, InvalidNodeTypeDefinitionException, NodeTypeExistsException, 
          UnsupportedRepositoryOperationException, RepositoryException;
      

        Activity

        Hide
        stefan_guggisberg added a comment - - edited

        i agree in general with adding support for registering node types defined in the CND format.

        some (minor) issues:

        • CND is defined in the appendix of the JCR 2.0 specification, hence it's "non-normative".
          i guess we'll have to 'promote' the CND format to be normative or add some clarifying
          language.
        • i don't think that we need 3 separate signatures. registerNodeTypes(InputStream stream, boolean allowUpdate)
          should be perfectly fine since getting an InputStream from a File (FileInputStream) or
          URL (URL#openStream()) is trivial.
        Show
        stefan_guggisberg added a comment - - edited i agree in general with adding support for registering node types defined in the CND format. some (minor) issues: CND is defined in the appendix of the JCR 2.0 specification, hence it's "non-normative". i guess we'll have to 'promote' the CND format to be normative or add some clarifying language. i don't think that we need 3 separate signatures. registerNodeTypes(InputStream stream, boolean allowUpdate) should be perfectly fine since getting an InputStream from a File ( FileInputStream ) or URL ( URL#openStream() ) is trivial.
        Hide
        rhauch added a comment -

        Regarding the 3 signatures, I almost proposed just the one, but thought the URL and File forms are indeed useful and worth giving it a shot considering that those are likely to be the most used in real deployments. Two additional methods in an API don't seem a burden for implementers, but it does IMO make it easier and more intuitive for client developers (which seems like the primary goal of the API).

        If consensus is to have just one, then that's fine.

        Show
        rhauch added a comment - Regarding the 3 signatures, I almost proposed just the one, but thought the URL and File forms are indeed useful and worth giving it a shot considering that those are likely to be the most used in real deployments. Two additional methods in an API don't seem a burden for implementers, but it does IMO make it easier and more intuitive for client developers (which seems like the primary goal of the API). If consensus is to have just one, then that's fine.
        Hide
        thomasmueller2 added a comment -

        Hi,

        This is a nice feature!

        In my view, just one method (registerNodeTypes(InputStream stream, boolean allowUpdate)) is sufficient, for the reasons outlined by Stefan.

        Regards,
        Thomas

        Show
        thomasmueller2 added a comment - Hi, This is a nice feature! In my view, just one method (registerNodeTypes(InputStream stream, boolean allowUpdate)) is sufficient, for the reasons outlined by Stefan. Regards, Thomas
        Hide
        rhauch added a comment -

        Okay, I've amended the description above to propose adding only the one method that takes an InputStream as the first parameter.

        Any other questions or concerns about the suggested signature and JavaDoc?

        Show
        rhauch added a comment - Okay, I've amended the description above to propose adding only the one method that takes an InputStream as the first parameter. Any other questions or concerns about the suggested signature and JavaDoc?
        Hide
        Peeter Piegaze added a comment -

        I will add the new signature (the Inputstream only) and explanation to the source and spec.

        Show
        Peeter Piegaze added a comment - I will add the new signature (the Inputstream only) and explanation to the source and spec.
        Hide
        Peeter Piegaze added a comment -

        Fixed: new signature added to spec and source

        Show
        Peeter Piegaze added a comment - Fixed: new signature added to spec and source

          People

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

            Dates

            • Created:
              Updated:
              Resolved: