1 2 Previous Next 17 Replies Latest reply on Sep 28, 2006 10:20 AM by adrian.brock

    Updating docs

    starksm64

      I did an initial pass at updating the vdf docs and classes:
      http://wiki.jboss.org/wiki/Wiki.jsp?page=JBoss5DeploymentFramework

      One issue with documenting the behavior is that a lot of the current behavior is part of the current plugin implementation. Tieing this into the metadata sharing, aspect configuration, etc. still needs to be fleshed out.

        • 1. Re: Updating docs
          starksm64

          As part of the docs, we need more info on the contracts. The following unused Deployer methods need explanation:
          + void prepareDeploy(DeploymentUnit unit) throws DeploymentException;
          + void handoff(DeploymentUnit from, DeploymentUnit to) throws DeploymentException;
          + void commitUndeploy(DeploymentUnit unit);

          • 2. Re: Updating docs

            They express an intention to implement 2 phase deployment
            and atomic redeployment.

            new.prepareDeploy() // take the new deployment to the ready stage
            old.prepareUndeploy() // get ready to undeploy
            handoff(new, old); // handover control
            new.commitDeploy(); // you are now in control
            old.commitUndeploy(); // you are out of here

            I doubt the final api will be this simple since it will have to deal
            with mutliple deployers on multiple aspects of the deployment. :-)

            For now, the AbstractSimpleDeployer is a better api
            with its deploy()/undeploy()

            In fact, I'm aiming for an api where the deployers don't
            really deal with the lifecycle directly and instead provide
            metadata on which parts of the deployment they want
            to do work on and "when".

            e.g.
            SARDeployer
            I create a ServiceDeployment and LoaderRepositoryConfig from -service.xml

            ServiceDeploymentDeployer
            I split a ServiceDeployment into its component ServiceMetaData

            ServiceClassLoaderDeployer
            I create classloaders from LoaderRepositoryConfig

            ServiceDeployer
            I'm the real deployer of ServiceMetaData

            etc.

            • 3. Re: Updating docs
              starksm64

               

              "adrian@jboss.org" wrote:

              In fact, I'm aiming for an api where the deployers don't
              really deal with the lifecycle directly and instead provide
              metadata on which parts of the deployment they want
              to do work on and "when".

              e.g.
              SARDeployer
              I create a ServiceDeployment and LoaderRepositoryConfig from -service.xml

              ServiceDeploymentDeployer
              I split a ServiceDeployment into its component ServiceMetaData

              ServiceClassLoaderDeployer
              I create classloaders from LoaderRepositoryConfig

              ServiceDeployer
              I'm the real deployer of ServiceMetaData

              etc.


              This makes more sense. My only question is whether there are distinct outputs for the runtime metadata and management interface. Having to create management views from the raw deployer metadata is too cumbersome and does not lend itself to introduction of higher level notions like extracting server wide views like all network ports in use. So an explicit management view like the ManagedObject notion that existed previously is something that should show up in a Deployer contract.


              • 4. Re: Updating docs

                 

                "scott.stark@jboss.org" wrote:
                My only question is whether there are distinct outputs for the runtime metadata and management interface. Having to create management views from the raw deployer metadata is too cumbersome and does not lend itself to introduction of higher level notions like extracting server wide views like all network ports in use. So an explicit management view like the ManagedObject notion that existed previously is something that should show up in a Deployer contract.


                Yes, but in principle the ManagedObject can be constructed from
                the raw metadata/real object by correctly annotating it
                either in the metadata or on the object.

                This is a similar mechanism to how the OpenMBean stuff works
                (or at least will work in JMX2.0) except we will likely need a
                richer annotation set and some conventions:

                e.g.
                public class MyClass
                {
                 // Annotated valid values and the config impact
                 @ValidValues(min=1, max=100)
                 @ConfigImpact(Impact.RUNTIME_CONFIGURABLE)
                 public int setPercentage() {}
                
                 // Effectively inject the port configuration
                 public void setServerSocket(ServerSocket socket) {}
                
                 @Statistics // or with MyStats suitably annotated
                 public MyStats getStats() {};
                }
                


                From this kind of thing, a ManagedObject can be constructed that is
                easier to handle by the management layer.

                • 5. Re: Updating docs
                  starksm64

                  Possibly, but my concern with this is its pushing too many management details to the bean developers. As long as there is an ability to override/map the raw metadata info to a management view it will work. I guess this really maps to having a ManagementViewDeployer whose output is the tool oriented ManagedObject with its input being the previous deployer metadata and optional ManagementViewDeployer override metadata.

                  • 6. Re: Updating docs

                     

                    "scott.stark@jboss.org" wrote:
                    Possibly, but my concern with this is its pushing too many management details to the bean developers.


                    On the contrary, keeping the two together is the only way it is going
                    to remain in anyway in synch.

                    I do see the need for being able to override what the bean developer
                    thought (or didn't think) was a good idea.
                    Or maybe just plain forgot, thus requiring retrofitting the description.

                    • 7. Re: Updating docs
                      starksm64

                      Yes, this was the conclusion reached with the network team.

                      • 8. Re: Updating docs
                        starksm64

                        I have updated the class diagrams and overview page to give a brief description of every abstract deployer since this is really where the deployer contract is evident currently.

                        One behavior I don't understand is the AbstractParsingDeployer placing the deployment type parse result created in createMetaData into the DeploymentUnit.getTransientManagedObjects() attachments. I would expect that which attachment map was populated would be something that was selected by an argument to createMetaData. What is the reason for only populating the getTransientManagedObjects() attachments?

                        • 9. Re: Updating docs

                          If a metadata file is being parsed then it is potentially
                          something that could be passed in as a predetermined managed object.

                          i.e. You override the factory settings using the profile service
                          or a management tool.

                          To identify what is overridable (it is parsed from metadata files),
                          it populates the transient managed objects which the
                          profile service/front end can override by promoting the modified object to
                          the predetermined section.

                          They are different from the plain attachments which
                          are just temporary artifacts of the deployment that deployers
                          use to communicate with each other.

                          P.S. Not sure that managed object is a good name for this
                          since it conflicts with the real managed object created from
                          this object + annotations on the class.

                          Metadata is probably better but that also conflicts?

                          • 10. Re: Updating docs
                            starksm64

                            I guess the issue arises from trying to distinguish between classes of metadata attachments at the structural level: getPredeterminedManagedObjects, getTransientManagedObjects, getTransientAttachments.

                            Its not clear that this can be manged easily. There are two problems I see with getting to the ultimate, fully resolved metadata. I see two distinct classes of metadata: Configuration and Managment.

                            Both are built from different sources and scopes:
                            - annotations
                            - descriptors
                            - overrides: vendor descriptors, profile service/management tools
                            - aspects: deployment and runtime

                            Both are graphs of objects whose nodes can be populated at any level. This is the metadata repository notion we have, that is not explicitly part of the current vdf spi. I don't see how we can build the object graphs without the metadata repository notion integrated. The two problems are 1, piecewise population of the object graph nodes, 2, seamless usage of the final, merged object.

                            Let's take a concrete example of a java:comp/env object:

                            class Binding
                            {
                             /** enc relative name of the binding */
                             String name;
                             /** type of the binding */
                             Class type;
                             /** value of the binding */
                             Object value;
                            }
                            class Link extends Binding
                            {
                             /** the raw link */
                             String link;
                             /** the raw link type */
                             enum LinkType {JndiName, DeploymentRef, ...} linkType;
                             /** the resolved name for the binding of the link */
                             String resolvedName;
                            }
                            
                            /** Some derived property that allows a mgmt tool to list the enc bindings */
                            @ManagedProperies({@MangedProperty("all-bindings") })
                            class ENCMetadata
                            {
                             /** simple direct bindings in the enc */
                             List<Binding> bindings;
                             /** links to bindings outside of the enc */
                             List<Link> links;
                            }
                            


                            This info is going to come from all levels:
                            - annotations on the component the enc belongs to
                            - deployment descriptor overrides
                            - container overrides: for example, we introduce non-standard elements like the security domain name, current subject, as well as the standard container bindings; orb, tm, pm.
                            - references to profile service managed bindings. One example would be property style references to elements managed at higer levels such as server hostname, logical name, cluster name, ...
                            ...

                            Ultimately an ENCAspect wants to install the javax.naming.Context for the ENCMetadata instance for the component its currently handling. Likewise, a management tools wants the to be able to display some representation of this Context.

                            How this is pulled together from the current vdf classes is far from clear for me with the current spi.


                            • 11. Re: Updating docs
                              starksm64

                              I am currently trying to pull together a more intuitive interface for the tasks of populating the metadata and consuming it by integrating the metadata repository into the vdf.

                              • 12. Re: Updating docs

                                I don't understand what you are trying to do?

                                There should be no merging for display to the user, that would
                                be pointless.

                                e.g. If the default DataSource is set in the metadata
                                at the deployment level or server level you don't want to merge this into the
                                ejb instance view.
                                The user cannot change the global default value by modifying a
                                single ejb.

                                This default metadata is in a seperate deployment.

                                The only merging would be explaining to the user where a
                                particular value came from and potentially providing a unified
                                editiing tool that explains to them that they are either changing
                                a global default or they are overriding it for their particualr
                                deployment, instance, etc.

                                • 13. Re: Updating docs

                                   

                                  "scott.stark@jboss.org" wrote:
                                  I am currently trying to pull together a more intuitive interface for the tasks of populating the metadata and consuming it by integrating the metadata repository into the vdf.


                                  The first step is introduce the mechanism where each context
                                  gets two scopes.
                                  1) Their mutable metadata that they modify/populate
                                  2) The metadata hierarchy they belong to.

                                  Besides the mutable metadata contexts belonging to the deployers
                                  there also needs to be a deployer that can populate the other
                                  contexts from metadata deployments.

                                  Since this involves injection/dependency of configuration
                                  into other objects this correctly belongs in the Controller.

                                  i.e. At runtime, yes it is ok to do
                                  MetaData.getAnnotation() for simple configuration
                                  but at deployment time it requires resolution of dependencies
                                  some of which will described on the annotation itself.

                                  If you don't believe me, think about what happens when
                                  you redeploy the metadata deployment that contains a default.
                                  configuration.
                                  Shouldn't this "redeploy" all the deployments that use this
                                  to update to the new value?

                                  Also, such a redeployment is necessary if user defined metadata could
                                  affect the classloading model when the classes/annotations, etc.
                                  change.

                                  • 14. Re: Updating docs
                                    starksm64

                                     

                                    "adrian@jboss.org" wrote:

                                    There should be no merging for display to the user, that would
                                    be pointless.

                                    e.g. If the default DataSource is set in the metadata
                                    at the deployment level or server level you don't want to merge this into the
                                    ejb instance view.
                                    The user cannot change the global default value by modifying a
                                    single ejb.

                                    This default metadata is in a seperate deployment.

                                    The only merging would be explaining to the user where a
                                    particular value came from and potentially providing a unified
                                    editiing tool that explains to them that they are either changing
                                    a global default or they are overriding it for their particualr
                                    deployment, instance, etc.

                                    The issue is illustrated by the enc example in that multiple scopes and sources of metadata go into the object that is used to create the javax.naming.Context that will be installed for a given component enc context.

                                    The default DataSource does need to get merged (resolved is a better term, maybe that is the confusion) into the cmp2 metadata. If I have not specified it via an annotation or descriptor, it has to be picked up from an encompassing scope.

                                    1 2 Previous Next