[gatein-commits] gatein SVN: r9140 - epp/docs/branches/6.0/Admin_Guide/en-US.

Author: rdickens Date: 2013-02-11 22:45:58 -0500 (Mon, 11 Feb 2013) New Revision: 9140 Modified: epp/docs/branches/6.0/Admin_Guide/en-US/chapter-1-Introduction.xml Log: Review and minor editing of chapter 1 Modified: epp/docs/branches/6.0/Admin_Guide/en-US/chapter-1-Introduction.xml =================================================================== --- epp/docs/branches/6.0/Admin_Guide/en-US/chapter-1-Introduction.xml 2013-02-11 15:09:40 UTC (rev 9139) +++ epp/docs/branches/6.0/Admin_Guide/en-US/chapter-1-Introduction.xml 2013-02-12 03:45:58 UTC (rev 9140) @@ -5,7 +5,7 @@ ]> <chapter id="sid-8094332_GateInManagement-Introduction"> <title>Introduction</title> - <para>The management component of the portal allows portal resources to be managed over commons interfaces like REST, CLI, and Portlets/Gadgets. This guide will discuss these interfaces as well as general portal management concepts and terms. It will then discuss specific management extensions included in the portal.</para> + <para>The management component of the portal allows a portal's resources to be managed over common interfaces such as REST, a CLI, and portlets/gadgets. This guide will discuss these interfaces as well as general portal management concepts and terms. It will then discuss specific management extensions included in the portal.</para> <section id="sid-8094332_GateInManagement-Terms"> <title>Terms</title> <informaltable> @@ -34,8 +34,7 @@ </row> <row> <entry> - <para> Managed Component - + <para>Managed Component </para> </entry> <entry> @@ -46,13 +45,11 @@ <entry> <para> Managed Resource - </para> </entry> <entry> <para> - A managed resource is a uniquely identified self describing &apos;resource&apos; which can have operations and sub-resources registered to it. - + A managed resource is a uniquely identified self-describing &apos;resource&apos; which can have operations and sub-resources registered to it. </para> </entry> </row> @@ -66,7 +63,6 @@ <entry> <para> A managed resource whose parent is also a managed resource. - </para> </entry> </row> @@ -74,13 +70,11 @@ <entry> <para> Address - </para> </entry> <entry> <para> - A management address is just the path of the managed resource with syntax similar to a file on a file system, ie: /foo/bar - + A management address is the path of the managed resource with syntax similar to a file on a file system, ie: /foo/bar </para> </entry> </row> @@ -88,13 +82,11 @@ <entry> <para> Operation - </para> </entry> <entry> <para> An action that can be performed on a managed resource. - </para> </entry> </row> @@ -102,13 +94,11 @@ <entry> <para> Attributes - </para> </entry> <entry> <para> Custom input parameters available to operations. - </para> </entry> </row> @@ -118,14 +108,14 @@ </section> <section id="sid-8094332_GateInManagement-Goals"> <title>Goals</title> - <para>The management component provides a foundation for managing portal side components. By doing so it allows management extensions to register resources and operations over a set of API&apos;s, which in turn allows us to expose these over common interfaces like REST and CLI. In other words, management extensions do not have to worry about the interfaces in which they will be managed over. This allows us to add additional interfaces without needing to change anything. Also by providing a set of API&apos;s to obtain managed resources, interfaces are built in a consistent manner. So managing the same component in one interface should be very similar if you were to manage it in another.</para> + <para>The management component provides a foundation for managing portal side components. By doing so it allows management extensions to register resources and operations over a set of APIs, which in turn allows us to expose these over common interfaces such as REST and a CLI. This approach means that management extensions are independent of their interfaces, allowing for additional interfaces to be added without changes to the extensions themselves. Providing a set of APIs to obtain managed resources results in interfaces built in a consistent manner. Managing the same component should be similar, regardless of the interface.</para> </section> <section id="sid-8094332_GateInManagement-Operations"> <title>Operations</title> <para> - The following operations are operations that have been identified by the management component to be common to most management extensions. The + The following operations are common to most management extensions. The <code>read-resource</code> - operation is really the only global operation supported in the core framework, all other operations need to be implemented by the extensions, since these would be specific to each extension. + operation is the only global operation supported in the core framework. All other operations need to be implemented by the extensions, since they are extension-specific. </para> <informaltable> <tgroup cols="2"> @@ -152,9 +142,9 @@ </entry> <entry> <para> - The read-resource operation is responsible for reading the managed resource; describing itself and listing any operations and/or sub-resources it may contain. + The read-resource operation is responsible for reading the managed resource; describing itself and listing any operations and/or sub-resources it may contain. - This is the primary operation to obtain information about a managed component and it&apos;s managed resources. + This is the primary operation to obtain information about a managed component and its managed resources. </para> </entry> </row> @@ -166,7 +156,7 @@ </para> </entry> <entry> - <para>The add-resource operation is responsible for adding/creating additional managed resources.</para> + <para>The <systemitem>add-resource</systemitem> operation is responsible for adding/creating additional managed resources.</para> </entry> </row> <row> @@ -177,7 +167,7 @@ </para> </entry> <entry> - <para>The remove-resource operation is responsible for removing/deleting an existing managed resource.</para> + <para>The <systemitem>emove-resource</systemitem> operation is responsible for removing/deleting an existing managed resource.</para> </entry> </row> <row> @@ -185,7 +175,7 @@ <para>update-resource</para> </entry> <entry> - <para>The update-resource operation is responsible for updating an existing managed resources state.</para> + <para>The <systemitem>update-resource</systemitem> operation is responsible for updating an existing managed resource's state.</para> </entry> </row> <row> @@ -196,7 +186,7 @@ </para> </entry> <entry> - <para>The read-config-as-xml operation is responsible for representing the current managed resource as xml configuration.</para> + <para>The <systemitem>read-config-as-xml</systemitem> operation is responsible for representing the current managed resource as an XML configuration.</para> </entry> </row> <row> @@ -208,11 +198,11 @@ </entry> <entry> <para> - The export-resource operation is responsible for exporting a managed resource in a format that is acceptable and used in an import. The export-resource is special in the + The <systemitem>export-resource</systemitem> operation is responsible for exporting a managed resource in a format that is acceptable and used in an import. The export-resource is special in the - sense that there&apos;s built-in functionality to recursively traverse managed resources until it finds one that supports an export-resource operation. In other words you can + sense that there is built-in functionality to recursively traverse managed resources until it finds one that supports an export-resource operation. In other words you can - register an export-resource operation on a sub-resource and it will be executed even by calling export-resource on any of it&apos;s ancestors. + register an export-resource operation on a sub-resource and it will be executed even by calling export-resource on any of its ancestors. </para> </entry> @@ -226,7 +216,7 @@ </entry> <entry> <para> - The import-resource operation is responsible for importing managed resources previously exported through an export-resource operation. + The <systemitem>import-resource</systemitem> operation is responsible for importing managed resources previously exported through an export-resource operation. </para> </entry> @@ -237,12 +227,12 @@ </section> <section id="sid-8094332_GateInManagement-ContentType"> <title>Content Type</title> - <para>Content type defines the format of management requests/responses. The three content types supported at the moment are json, xml, and zip. Since read-config-as-xml (xml), export-resource (zip), and import-resource (zip) are content type specific operations, the response must be in that format. Other then that it&apos;s up to the extension on which content type is supported for each operation.</para> + <para>Content type defines the format of management requests/responses. The three content types supported at the moment are JSON, XML, and Zip. Since read-config-as-xml (XML), export-resource (Zip), and import-resource (Zip) are content type specific operations, the response must be in the same format. Aside from this restriction, it is up to the extension as to which content type is supported for each operation.</para> </section> <section id="sid-8094332_GateInManagement-PathTemplates"> <title>Path Templates</title> <para> - Path templates are something that management extensions use to define dynamic content when registering resources. These path template variables are used during an export-resource to filter these managed resources. By specifying the + Path templates are used by management extensions to define dynamic content when registering resources. These path template variables are used during an export-resource operation to filter these managed resources. By specifying the <code>filter</code> attribute of an export-resource operation, managed resources can be explicitly included or excluded during export. </para> @@ -253,7 +243,7 @@ </example> <para>where path-var is the path template variable name, name is the name of a managed-resource, and the &apos;!&apos; char, which is optional, is to exclude that resource rather then include it. Below are some examples that use the path template variable &apos;foo&apos;:</para> <example> - <title>Only include managed resource &apos;bar&apos;</title> + <title>Include managed resource &apos;bar&apos;</title> <programlisting>foo:bar</programlisting> </example> <example>