Author: smumford Date: 2011-11-11 01:05:38 -0500 (Fri, 11 Nov 2011) New Revision: 8043 Removed: epp/docs/branches/5.2/Admin_Guide/en-US/chapter-1-GateIn_Management.xml Log: Removing unnecessary build files from svn Deleted: epp/docs/branches/5.2/Admin_Guide/en-US/chapter-1-GateIn_Management.xml =================================================================== --- epp/docs/branches/5.2/Admin_Guide/en-US/chapter-1-GateIn_Management.xml 2011-11-11 06:04:07 UTC (rev 8042) +++ epp/docs/branches/5.2/Admin_Guide/en-US/chapter-1-GateIn_Management.xml 2011-11-11 06:05:38 UTC (rev 8043) @@ -1,775 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> - -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "Admin_Guide.ent"> -%BOOK_ENTITIES; -]> - -<chapter id="chap-Admin_Guide-JBoss_Enterprise_Portal_Platform_Management"> - <title>JBoss Enterprise Portal Platform Management</title> - <section id="sect-Admin_Guide-JBoss_Enterprise_Portal_Platform_Management-Introduction"> - <title>Introduction</title> - - <para> - The gatein-management component of the portal allows portal resources to be managed over commons interfaces like REST, CLI, and Portlets/Gadgets. This guide will discuss how to use these interfaces along with describing gatein-management concepts and terms. - </para> - - <note> - <para> - This documentation is a work in progress. - </para> - </note> - - <section id="sect-Admin_Guide-Introduction-Terms"> - <title>Terms</title> - - <table> - <title></title> - <tgroup cols="2"> - <thead> - <row> - <entry> - <para> - Term - </para> - </entry> - <entry> - <para> - Description - </para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para> - Management Extension - </para> - </entry> - <entry> - <para> - An extension to the management system which defines a managed component. - </para> - </entry> - </row> - <row> - <entry> - <para> - Managed Component - </para> - </entry> - <entry> - <para> - A managed component, which has been registered via an extension, serves as the root managed resource for a component. - </para> - </entry> - </row> - <row> - <entry> - <para> - Managed Resource - </para> - </entry> - <entry> - <para> - A managed resource is a uniquely identified self describing 'resource' which can have operations and sub-resources registered to it. - </para> - </entry> - </row> - <row> - <entry> - <para> - Sub-resource - </para> - </entry> - <entry> - <para> - A managed resource whose parent is also a managed resource. - </para> - </entry> - </row> - <row> - <entry> - <para> - Operation - </para> - </entry> - <entry> - <para> - An action that can be performed on a managed resource. - </para> - </entry> - </row> - <row> - <entry> - <para> - Attributes - </para> - </entry> - <entry> - <para> - Custom input parameters available to operations. - </para> - </entry> - </row> - </tbody> - </tgroup> - </table> - </section> - - <section id="sect-Admin_Guide-Introduction-Goals"> - <title>Goals</title> - - <para> - The gatein-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's, which in turn allows us to expose these over common interfaces like REST and CLI. In other words, management extensions don't 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'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> - </section> - - <section id="sect-Admin_Guide-Introduction-Operations"> - <title>Operations</title> - - <para> - The following operations are common operation names that have been identified by the gatein-management component. These operation names should be used by extensions when the scenario fits. The <emphasis role="strong">read-resource</emphasis> operation is the only operation that is built into the gatein-management component. All other operations need to be implemented by the extensions themselves. - </para> - - <table> - <title></title> - <tgroup cols="2"> - <thead> - <row> - <entry> - <para> - Operation Name - </para> - </entry> - <entry> - <para> - Description - </para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para> - read-resource - </para> - </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. This is the primary operation to obtain information about a managed component and it's managed resources. - </para> - </entry> - </row> - <row> - <entry> - <para> - add-resource - </para> - </entry> - <entry> - <para> - The add-resource operation is responsible for adding/creating additional managed resources. - </para> - </entry> - </row> - <row> - <entry> - <para> - remove-resource - </para> - </entry> - <entry> - <para> - The remove-resource operation is responsible for removing/deleting an existing managed resource. - </para> - </entry> - </row> - <row> - <entry> - <para> - update-resource - </para> - </entry> - <entry> - <para> - The update-resource operation is responsible for updating an existing managed resources state. - </para> - </entry> - </row> - <row> - <entry> - <para> - read-config-as-xml - </para> - </entry> - <entry> - <para> - The read-config-as-xml operation is responsible for representing the current managed resource as xml configuration. - </para> - </entry> - </row> - <row> - <entry> - <para> - export-resource - </para> - </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 sense that there's 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's ancestors. - </para> - </entry> - </row> - <row> - <entry> - <para> - import-resource - </para> - </entry> - <entry> - <para> - The import-resource operation is responsible for importing managed resources previously exported through an export-resource operation. - </para> - </entry> - </row> - </tbody> - </tgroup> - </table> - </section> - - <section id="sect-Admin_Guide-Introduction-Content_Type"> - <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's up to the extension on which content type is supported for each operation. - </para> - </section> - - <section id="sect-Admin_Guide-Introduction-Filtering"> - <title>Filtering</title> - - <para> - Filtering is a special attribute used during the export-resource operation, which filters managed resources that have been registered via a path template. See the Developer's Guide section for more information on path templates <emphasis role="italics">(TODO: Link to JBoss Enterprise Portal Platform Management section of Developer Guide)</emphasis> . The attribute name is 'filter' and the format can be defined as: - </para> - - <example id="exam-Admin_Guide-Filtering-Exclude_at_a_path"> - <title>Exclude at a path</title> -<programlisting>[path-var]:(!)?[name],...[name]</programlisting> - </example> - - <para> - Where path-var is the path template variable name defined in an extension, name is the name of the managed-resource, and the '!' char is to declare the filter as an exclusion. Below are some examples that use the path template variable 'foo': - </para> - - <example id="exam-Admin_Guide-Filtering-Only_include_managed_resource_bar"> - <title>Only include managed resource 'bar'</title> -<programlisting>foo:bar</programlisting> - </example> - - <example id="exam-Admin_Guide-Filtering-Include_managed_resource_bar_and_foo_bar"> - <title>Include managed resource 'bar' and 'foo-bar'</title> -<programlisting>foo:bar,foo-bar</programlisting> - </example> - - <example id="exam-Admin_Guide-Filtering-Exclude_managed_resource_bar"> - <title>Exclude managed resource 'bar'</title> -<programlisting>foo:!bar</programlisting> - </example> - - <example id="exam-Admin_Guide-Filtering-Exclude_managed_resource_bar_and_foo_bar"> - <title>Exclude managed resource 'bar' and 'foo-bar'</title> -<programlisting>foo:!bar,foo-bar</programlisting> - </example> - </section> - - <section id="sect-Admin_Guide-Introduction-Source"> - <title>Source</title> - - <para> - The source is available on github @ - <ulink url="https://github.com/gatein/gatein-management" /> - </para> - </section> - </section> - <section id="sect-Admin_Guide-JBoss_Enterprise_Portal_Platform_Management-REST_Component"> - <title>REST Component</title> - - <para> - The gatein-management REST component is responsible for mapping restful requests to management requests. It does this by locating the managed resource by mapping the request URL to a management address and then invoking an operation on that managed resource. It defines an entry point for RESTful clients, and exposes the registered managed resources and operations over REST. - </para> - - <section id="sect-Admin_Guide-REST_Component-Entry_Point_URL"> - <title>Entry Point URL</title> - - <para> - To gain access to gatein-management resources and operations over REST a RESTful client must know the entry point URL, which is defined as follows: - </para> - - <para></para> - - <para> - http(s)://&lt;host&gt;:&lt;port&gt;/&lt;rest-context-name&gt;/private/managed-components - </para> - - <para> - where the rest-context-name is the portal container's rest context name. So for the default portal, the rest context name is 'rest'. - </para> - - <note> - <title>Default Entry Point</title> - <para> - <ulink url="http://localhost:8080/rest/private/managed-components/" /> - </para> - </note> - - <note> - <para> - The REST URL is protected, and the authenticated user must belong to the 'administrators' group of the portal. - </para> - </note> - </section> - - <section id="sect-Admin_Guide-REST_Component-Resource_URLs"> - <title>Resource URLs</title> - - <para> - REST resource URLs are mapped to management addresses, and since every managed resource has a unique management address, every managed resource can be represented by a unique REST URL. The URL for identifying managed resources is as follows: - </para> - - <para> - <ulink type="http" url="http://&lt;host&gt;:&lt;port&gt;/&lt;rest-context-name&gt;/private/managed-components/&lt;component-name&gt;/&lt;managed-resource-name&gt;/&lt;sub-resource-name&gt;/.../&lt;sub-resource-name&gt;" /> - </para> - - <important> - <title>Example</title> - <para> - <ulink url="http://localhost:8080/rest/private/managed-components/foo/bar/foo-bar" /> - </para> - </important> - - <para> - The URL above uniquely identifies a managed resource named 'foo-bar', which is a sub-resource of 'bar', and 'bar' being a managed resource of the managed component 'foo'. - </para> - </section> - - <section id="sect-Admin_Guide-REST_Component-Operations"> - <title>Operations</title> - - <para> - To map a RESTful request to an operation, two strategies are used. One strategy maps the actual HTTP method of the REST request to built-in management operations, and the other is specifying the operation by adding a query parameter. - </para> - - <section id="sect-Admin_Guide-Operations-HTTP_Method"> - <title>HTTP Method</title> - - <table> - <title></title> - <tgroup cols="2"> - <thead> - <row> - <entry> - <para> - HTTP Method - </para> - </entry> - <entry> - <para> - Management Operation - </para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para> - GET - </para> - </entry> - <entry> - <para> - read-resource - </para> - </entry> - </row> - <row> - <entry> - <para> - PUT - </para> - </entry> - <entry> - <para> - update-resource - </para> - </entry> - </row> - <row> - <entry> - <para> - POST - </para> - </entry> - <entry> - <para> - add-resource - </para> - </entry> - </row> - <row> - <entry> - <para> - DELETE - </para> - </entry> - <entry> - <para> - remove-resource - </para> - </entry> - </row> - </tbody> - </tgroup> - </table> - - <para> - This means that the same URL can invoke 4 different operations just by changing the HTTP method of the REST request. - </para> - </section> - - <section id="sect-Admin_Guide-Operations-Request_Parameter"> - <title>Request Parameter</title> - - <para> - Since gatein-management supports more then just four operations, operations can also be explicitly defined by including request parameters of the REST request. By adding the query parameter 'op' to the request URL, clients can define what operation to invoke. - </para> - - <important> - <title>Example</title> - <para> - <ulink url="http://localhost:8080/rest/private/managed-components/foo/bar?op=some-custom-operation" /> - </para> - </important> - - <note> - <title>Following URLs are equivalent for a GET request</title> - <para> - <ulink url="http://localhost:8080/rest/private/managed-components/foo/bar" /> - <ulink url="http://localhost:8080/rest/private/managed-components/foo/bar?op=read-resource" /> - </para> - </note> - </section> - - <section id="sect-Admin_Guide-Operations-URL_Extension"> - <title>URL Extension</title> - - <para> - Sometimes it's nice to represent REST resources as a file, so two URL extensions have been added to support two common operations: read-config-as-xml and export-resource. By adding the following URL extensions at the end of the request, you can invoke these two operations. - </para> - - <table> - <title></title> - <tgroup cols="3"> - <thead> - <row> - <entry> - <para> - URL Extension - </para> - </entry> - <entry> - <para> - Management Operation - </para> - </entry> - <entry> - <para> - Example URL - </para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para> - .xml - </para> - </entry> - <entry> - <para> - read-config-as-xml - </para> - </entry> - <entry> - <para> - <ulink url="http://localhost:8080/rest/private/managed-components/foo/bar.xml" /> - </para> - </entry> - </row> - <row> - <entry> - <para> - .zip - </para> - </entry> - <entry> - <para> - export-resource - </para> - </entry> - <entry> - <para> - <ulink url="http://localhost:8080/rest/private/managed-components/foo/bar.zip" /> - </para> - </entry> - </row> - </tbody> - </tgroup> - </table> - - <para></para> - - <note> - <title>Following URLs are equivalent</title> - <para> - <ulink url="http://localhost:8080/rest/private/managed-components/foo/bar.xml" /> - <ulink url="http://localhost:8080/rest/private/managed-components/foo/bar?op=read-config-as-xml" /> - </para> - </note> - </section> - </section> - - <section id="sect-Admin_Guide-REST_Component-Attributes"> - <title>Attributes</title> - - <para> - Attributes are mapped to a management request by including all request parameters of the request as attributes. So if an operation supports certain attributes, query parameters can be added to the request URL to be used as attributes of the management request. - </para> - - <important> - <title>Example</title> - <para> - <ulink url="http://localhost:8080/rest/private/managed-components/foo/bar?first-name=john&amp;last-name=doe" /> - </para> - </important> - - <section id="sect-Admin_Guide-Attributes-Multi_value_Attributes"> - <title>Multi-value Attributes</title> - - <para> - Since management requests can have multiple values for a single attribute name, it's easy to map HTTP query parameters (since it also accepts multiple values) to multi-value management request attributes. - </para> - - <important> - <title>Example</title> - <para> - <ulink url="http://localhost:8080/rest/private/managed-components/foo/bar?colors=red&amp;colors=green&amp;colors=blue" /> - </para> - </important> - </section> - </section> - - <section id="sect-Admin_Guide-REST_Component-Content_Negotiation"> - <title>Content Negotiation</title> - - <para> - gatein-management supports the concept of a 'Content Type' to indicate the format of management requests and responses, which maps to the content negotiation principle of REST. Clients can dictate the content type of the management request by specifying the Accept and Content-Type headers of the request. The 'Accept' header is to indicate what it wants to receive the response as, and the 'Content-Type' header is to specify what format the client is sending. Below is a list of request headers that map to a 'Content Type'. - </para> - - <table> - <title></title> - <tgroup cols="2"> - <thead> - <row> - <entry> - <para> - Header - </para> - </entry> - <entry> - <para> - Content Type - </para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para> - application/json - </para> - </entry> - <entry> - <para> - JSON - </para> - </entry> - </row> - <row> - <entry> - <para> - application/xml - </para> - </entry> - <entry> - <para> - XML - </para> - </entry> - </row> - </tbody> - </tgroup> - </table> - - <para></para> - - <note> - <para> - JSON is the default content type. - </para> - </note> - - <section id="sect-Admin_Guide-Content_Negotiation-Browser_Content_Negotiation"> - <title>Browser Content Negotiation</title> - - <para> - To make it easy to control the content type of management requests through the browser, the rest component of gatein-management supports the 'format' query parameter to dictate the format of the response. This is because most browsers already send an 'Accept' header. - </para> - - <important> - <title>Example</title> - <para> - <ulink url="http://localhost:8080/rest/private/managed-components/foo/bar?format=xml" /> - </para> - </important> - - <para> - Below is the supported 'format' parameters which map to a 'Content Type'. - </para> - - <table> - <title></title> - <tgroup cols="2"> - <thead> - <row> - <entry> - <para> - Format parameter - </para> - </entry> - <entry> - <para> - Content Type - </para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para> - format=json (default) - </para> - </entry> - <entry> - <para> - JSON - </para> - </entry> - </row> - <row> - <entry> - <para> - format=xml - </para> - </entry> - <entry> - <para> - XML - </para> - </entry> - </row> - </tbody> - </tgroup> - </table> - - <para></para> - - <note> - <para> - Content negotiation is ignored for content type specific operations such as 'read-config-as-xml' and 'export-resource' since these cannot return different formats. - </para> - </note> - </section> - </section> - </section> - <section id="sect-Admin_Guide-JBoss_Enterprise_Portal_Platform_Management-Command_Line_Interface"> - <title>Command Line Interface</title> - - <para> - The command line interface (CLI) for gatein management provides an interactive shell using CRaSH to map commands to management requests. It uses the CRaSH SSH plugin to connect over SSH. - </para> - - <note> - <para> - For more information on CRaSH please visit - <ulink url="http://code.google.com/p/crsh/" /> - . - </para> - </note> - - <section id="sect-Admin_Guide-Command_Line_Interface-Deploying_the_CLI"> - <title>Deploying the CLI</title> - - <para> - To deploy the CLI you must first build the gatein-management project. The source is available on - <ulink url="http://github.com/gatein/gatein-management">github</... - . Once built you can then deploy the web application to a JBoss Enterprise Portal Platform instance. - </para> - - <note> - <para> - The CLI web application must be deployed as an exploded war - </para> - </note> - </section> - - <section id="sect-Admin_Guide-Command_Line_Interface-Running_the_CLI"> - <title>Running the CLI</title> - - <para> - After deploying the CLI web application you can connect to the CLI over SSH. The default port is 2000. - </para> - - <important> - <title>Example</title> - <para> - ssh -p 2000 root@localhost - </para> - </important> - </section> - </section> - <section id="sect-Admin_Guide-JBoss_Enterprise_Portal_Platform_Management-Management_Extensions"> - <title>Management Extensions</title> - - <para> - Below will discuss specific management extensions included in JBoss Enterprise Portal Platform. - </para> - - <section id="sect-Admin_Guide-Management_Extensions-MOP_Extension"> - <title>MOP Extension</title> - - <para> - The MOP extension registers the 'mop' managed component which is responsible for managing pages, navigation, and site layout. It supports the read-config-as-xml, export-resource, and import-resource operations. The read-config-as-xml operation exposes pages, navigation, and site layout in the - <ulink url="http://www.gatein.org/xml/ns/">gatein-objects</ulink... - xml format which is found in when defining this content in a portal extension. - </para> - </section> - </section> -</chapter> -