[path-var]:(!)?[name],...[name];...[path-var]:(!)?[name],...[name]
The management component of the portal allows portal resources to be managed over common 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.
|
Term |
Description |
|
Management Extension |
An extension to the management system which defines a managed component. |
|
Managed Component |
A managed component, which has been registered via an extension, serves as the root managed resource for a component. |
|
Managed Resource |
A managed resource is a uniquely identified self describing 'resource' which can have operations and sub-resources registered to it. |
|
Sub-resource |
A managed resource whose parent is also a managed resource. |
|
Address |
A management address is just the path of the managed resource with syntax similar to a file on a file system, ie: /foo/bar |
|
Operation |
An action that can be performed on a managed resource. |
|
Attributes |
Custom input parameters available to operations. |
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'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.
The following operations are operations that have been identified by the management component to be common to most management extensions. The read-resource 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 Name |
Description |
|
read-resource |
The read-resource operation is responsible for reading the managed resource; describing itself and listing any operations and/or sub-resources it may contain. |
|
add-resource |
The add-resource operation is responsible for adding/creating additional managed resources. |
|
remove-resource |
The remove-resource operation is responsible for removing/deleting an existing managed resource. |
|
update-resource |
The update-resource operation is responsible for updating an existing managed resource's state. |
|
read-config-as-xml |
The read-config-as-xml operation is responsible for representing the current managed resource as xml configuration. |
|
export-resource |
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 |
|
import-resource |
The import-resource operation is responsible for importing managed resources previously exported through an export-resource operation. |
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 than that it's up to the extension which content type is supported for each operation.
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 filter attribute of an export-resource operation, managed resources can be explicitly included or excluded during export.
The filter attribute has the following value syntax:
[path-var]:(!)?[name],...[name];...[path-var]:(!)?[name],...[name]
where path-var is the path template variable name, name is the name of a managed-resource, and the '!' char, which is optional, is to exclude that resource rather then include it. Below are some examples that use the path template variable 'foo':
foo:bar
foo:bar,foo-bar
foo:!bar
foo:!bar,foo-bar
foo:bar,foo-bar;baz:blah
For more information on the usage of path templates specific to a management extension, see the management extensions section below.
The 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.
To gain access to management resources and operations over REST a RESTful client must know the entry point URL, which is defined as follows:
http(s)://<host>:<port>/<rest-context-name>/private/managed-components
Where the rest-context-name is the portal container's rest context name. So for the default portal, the rest context name is 'rest', and for a portal running on localhost and port 8080 the URL would be
http://localhost:8080/rest/private/managed-components/
The REST URL is protected, and the authenticated user must belong to the 'administrators' group of the portal.
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:
http://<host>:<port>/<rest-context-name>/private/managed-components/<component-name>/<managed-resource-name>/<sub-resource-name>/.../<sub-resource-name>
The URL below 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'.
http://localhost:8080/rest/private/managed-components/foo/bar/foo-bar
To map a RESTful request to an operation the REST component must somehow map the HTTP request to an operation name. It can achieve this by looking at three things (in order of precedence):
HTTP URL Parameters
URL Extension
The HTTP method of the request.
The following table shows which HTTP methods map to operation names.
|
HTTP Method |
Management Operation |
|
GET |
read-resource |
|
PUT |
update-resource |
|
POST |
add-resource |
|
DELETE |
remove-resource |
This means that the same URL can invoke four different operations just by changing the HTTP method of the REST request.
Since the management system supports more then just four operations, operations can also be explicitly defined by including HTTP parameters as part of the REST request. For example by adding the query parameter op to the request URL, clients can define what operation to invoke.
http://localhost:8080/rest/private/managed-components/foo/bar?op=some-custom-operation
It's best practice to use the HTTP method to dictate the operation name when it can. However nothing stops a client explicitly setting operation names as request parameters.
The following URL's are equivalent for a GET request:
Sometimes it's nice to represent REST resources as files, 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 URL, you can invoke these two operations.
|
URL Extension |
Management Operation |
Example URL |
|
.xml |
read-config-as-xml |
http://localhost:8080/rest/private/managed-components/foo/bar.xml |
|
.zip |
export-resource |
http://localhost:8080/rest/private/managed-components/foo/bar.zip |
This is just a convenient way to specify the operation name as a file extension instead of specifying it as a request parameter.
The following URL's are equivalent:
Management attributes (which are part of a management request) are mapped by including all request parameters of the HTTP 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.
http://localhost:8080/rest/private/managed-components/foo/bar?first-name=john&last-name=doe
Management attributes can be multi-valued (meaning more then one value associated with an attribute). This is easy as HTTP query parameters can be multi-valued as well.
http://localhost:8080/rest/private/managed-components/foo/bar?colors=red&colors=green&colors=blue
The management framework defines Content Type to indicate the format of management requests and responses. Clients can dictate the content type of the management request by specifying the Accept and Content-Type headers of the HTTP request. The Accept header indicates the format of the response and the Content-Type header specifies the format of the request. Below is a list of request headers that map to the Content Type of the management system.
|
Header |
Content Type |
|
application/json |
JSON |
|
application/xml |
XML |
|
application/zip |
ZIP |
JSON is the default content type.
To make it easy to control the content type of management requests through the browser, the rest component supports the format HTTP parameter to dictate the format of the response. This is because most browsers already send an 'Accept' header.
http://localhost:8080/rest/private/managed-components/foo/bar?format=xml
Below is the list of format HTTP parameters which map to Content Types.
|
Format parameter |
Content Type |
|
format=json (default) |
JSON |
|
format=xml |
XML |
Content negotiation is ignored for content type specific operations such as 'read-config-as-xml' and 'export-resource' since these cannot return different formats.
Since the read-resource operation is a built in operation provided by the management component, as opposed to extensions, below documents the format of the response.
GET /managed-components or GET /managed-components?op=read-resource
HTTP/1.1 200 OK
Content-Type: application/json
{
"description": "Available operations and children (sub-resources).",
"children": [
{
"name": "foo",
"description": "Some description",
"link": {
"rel": "child",
"href": "http://localhost:8080/rest/private/managed-components/foo"
}
}
],
"operations": [
{
"operation-name": "read-resource",
"operation-description": "Lists information about a managed resource, including available operations and children (sub-resources).",
"link": {
"rel": "self",
"href": "http://localhost:8080/rest/private/managed-components"
"type": "application/json"
"method": "get"
}
}
]
}
HTTP/1.1 200 OK
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<resource>
<description>Available operations and children (sub-resources).</description>
<children>
<child>
<name>foo</name>
<description>Some description</description>
<link href="http://localhost:8080/rest/private/managed-components/foo" rel="child"/>
</child>
</children>
<operations>
<operation>
<operation-name>read-resource</operation-name>
<operation-description>Lists information about a managed resource, including available operations and children (sub-resources).</operation-description>
<link href="http://localhost:8080/rest/private/managed-components" rel="self" type="application/xml" method="get"/>
</operation>
</operations>
</resource>
The command line interface (CLI) component provides an interactive shell using CRaSH to map commands to management requests. It connects over SSH, using the CRaSH SSH plugin.
For more information on CRaSH please visit http://code.google.com/p/crsh/.
To deploy the CLI you must first build the gatein-management project. The source is available on github. Once built you can then deploy the web application to GateIn:
cp cli/target/gatein-management-cli.war $JBOSS_HOME/standalone/deployments/
The CLI application is bundled with JBoss Portal Platform. Refer to the documentation at docs.redhat.com for more information.
After deploying the CLI web application you can connect to the CLI over SSH as follows
ssh -p <port> <user>@<host>
ssh -p 2000 root@localhost
You can change the default port that SSH listens on by changing the property crash.ssh.port in the WEB-INF/crash/crash.properties file.
# VFS configuration crash.vfs.refresh_period=1 # SSH configuration crash.ssh.port=2000
Make sure the configured port is open and not blocked by firewall settings.
The CLI component comes with a number of management commands that will execute operations on managed resources in the portal. For a listing of all commands available type in help in the shell. You can also add the help option -h or --help for each command for further information. Also the man command can be executed for even more detailed information about the command.
The mgmt command allows a user to connect and disconnect from the management system. It also provides an exec command which allows more custom control over executing operations with the management system.
% mgmt -h usage: mgmt[-h | --help] COMMAND [ARGS] The most commonly used mgmt commands are: exec Manually executes a management operation connect login to gatein management disconnect disconnect from management system % mgmt connect -h usage: mgmt [-h | --help] connect [-u | --username] [-p | --password] [-c | --container] [-h | --help] command usage [-u | --username] the user name [-p | --password] the user passowrd [-c | --container] portal container name (default is portal) %
The mgmt connect command allows the user to connect to the management system, optionally specifying a portal container (default is 'portal'). Since management commands are administrative operations, the user must authenticate again in order to validate authorization to the portal container.
% mgmt connect Password: Successfully connected to gatein management system: [user=root, container='portal', host='127.0.0.1'] [ /]%
% mgmt connect -u john -c sample-portal Password: Successfully connected to gatein management system: [user=john, container='sample-portal', host='127.0.0.1'] [ /]%
The mgmt exec command allows complete control over what to send to the management system.
[ /]% mgmt exec -h usage: mgmt [-h | --help] exec [-c | --contentType] [-f | --file] [-a | --attribute] [-o | --operation] path [-h | --help] command usage [-c | --contentType] content type of an operation [-f | --file] File name [-a | --attribute] Specifies an attribute. [-o | --operation] Operation name path [ /]%
[ /]% mgmt exec --operation read-config-as-xml --contentType xml /foo <?xml version='1.0' encoding='UTF-8'?> <data>...</data> [ /]%
The cat command executes the read-config-as-xml operation on a managed resource and outputs the xml data to the shell. Obviously the managed resource must support the read-config-as-xml operation.
[ /]% cat -h usage: cat [-h | --help] path [-h | --help] command usage path [ /]% cat /foo <?xml version='1.0' encoding='UTF-8'?> <data>...</data> [ /]%
The cd command changes the current path of the CLI.
[ /]% cd -h usage: cd [-h | --help] path [-h | --help] command usage path [ /]%
[ /]% cd /foo/bar [bar]%
The ls command executes the read-resource operation on the current (or specified by the path) managed resource.
[ /]% ls -h usage: ls [-h | --help] path [-h | --help] command usage path [ /]% ls foo bar [ /]% ls /foo baz [ /]%
The pwd command prints out the current resource path of the CLI.
[ /]% pwd -h usage: pwd [-h | --help] [-h | --help] command usage [ /]% pwd / [ /]% cd foo/baz [baz]% pwd /foo/baz [baz]%
The export operation executes the export-resource operation on a managed resource and writes the exported content to the file.
Since the CLI is connected to the portal server over SSH, the export command will write to the servers file system, not the client.
[ /]% export -h usage: export [-h | --help] [-f | --file] [-r | --filter] path [-h | --help] command usage [-f | --file] File name [-r | --filter] Specifies the value of the filter to use during an export for example. path [ /]%
[ /]% export --file /tmp foo Export complete ! File location: /tmp/foo_2011-10-21_18-29-36.zip [ /%]
If you only specify a directory the export command will write a file with the name of the managed resource and a timestamp.
[ /]% export --file /tmp/export-example.zip foo Export complete ! File location: /tmp/export-example.zip [ /%]
[ /]% export --file /tmp/export-filter-example.zip --filter bar:baz,foo-bar foo Export complete ! File location: /tmp/export-filter-example.zip [ /%]
The import command executes the import-resource operation on a managed resource.
[ /]% import -h usage: importfile [-h | --help] [-f | --file] [-m | --importMode] path [-h | --help] command usage [-f | --file] File name [-m | --importMode] The import mode for an import operation path [ /]%
Since the CLI is connected to the portal server over SSH, the import command must specify a file that exists on the server.
[ /]% import --file /tmp/foo.zip /foo Successfully imported file /tmp/foo.zip [ /]%
[ /]% import --file /tmp/foo.zip --importMode overwrite /foo Successfully imported file /tmp/foo.zip [ /]%
You can autocomplete the import modes by typing --importMode and hitting tab.
The CLI application supports SCP to execute the export-resource and import-resource operations in order to export to and import from a host other then the portal.
To execute the export-resource operation using SCP the source of the SCP command is the portal server and the target is the local file to export to.
$ scp -P <port> <user>@<host>:{portal-container}:{path} <file>
The portal-container is optional with default value being 'portal'. The path is the path of the resource supporting the export-resource operation.
So to export 'foo/bar' resource assuming the CLI is deployed to 'example.org'.
$ scp -P 2000 'root@example.org:portal:/foo/bar' bar.zip
Attributes like 'filter' can be added to the path of the SCP command just as you would add query parameters to a URL.
$ scp -P 2000 'root@example.org:portal:/foo/bar?filter=bar:baz,foo-bar' foo.zip
To execute the import-resource operation using SCP the source of the SCP command is the local file and the target is the portal server.
$ scp -P <port> <file> <user>@<host>:{portal-container}:{path}
The portal-container is optional with default value being 'portal'. The path is the path of the resource that supports the import-resource operation. So to import a foo.zip file to the /foo resource assuming the CLI is deployed to 'example.org'.
$ scp -P 2000 foo.zip 'root@example.org:portal:/foo'
More specific examples of the SCP command can be found below pertaining to that particular management extension.
The following management extensions supported in the portal are:
MOP Management Extension
The MOP management extension registers the 'mop' managed component which is responsible for managing pages, navigation, and site layout. It primarily supports exporting and importing this data through the export-resource and import-resource operations. It also supports the read-config-as-xml operation to expose the portal meta data as xml.
The read-config-as-xml operation can only be executed on the site layout, pages, and navigation managed resources. The xml format returned is that of which is defined in by the gatein-objects xsd. This means that these resources are exposed in the same format as what a portal extension would accept for importing data into the portal.
The export-resource operation can be executed on any resource of the MOP extension (including the mop component itself). Since the management system recursively searches for all sub-resources that have export-resource defined (which they are defined at the site layout, page, and navigation level), exports can be very granular.
The import-resource operation can only be executed at the mop component (root managed resource of the mop extension). This is because the exported zip file contains the path information (like site type and site name). So executing an import-resource operation on a group site, when the zip contains data from a portal site, doesn't make sense.
The MOP import-resource operation defines the importMode attribute as follows during import.
|
Mode |
Description |
|
conserve |
Import data only if no artifacts exist for that site. For example if one page exists for site 'classic', nothing will be imported. |
|
insert |
Import data when data does not exist, otherwise do nothing. |
|
merge |
Import when data does not exist, update data when it does exist. |
|
overwrite |
Delete all data for that artifact of the site, import new data. For example if the zip file only contains pages for site classic, then |
'merge' is the default importMode.
Below are the list of path template variables defined in the MOP management extension. These path template variables are used for filtering during export.
site-type
These are the site types of the portal to include or exclude. Available values are: portal, group, and user.
site-name
The sites to include or exclude. Examples could be classic and /platform/administrators.
site-layout
The name of the site layout depending on the site type. Available values are: portal, group, user.
page-name
The name of the page(s) to include or exclude.
nav-uri
The URI of the navigation node to include or exclude.
All URL's below are relative to the REST management entry point of the portal container.
For all read-config-as-xml refer http://www.gatein.org/xml/ns/gatein_objects_1_2 for the format of the XML.
The mop managed component resource (root managed resource) is the only resource that accepts the import-resource operation.
PUT /mop Headers: Content-Type: application/zip
HTTP/1.1 200 OK
The site layout resource represents the site layout of the portal. It's the data defined in the portal.xml, group.xml, and user.xml files (depending on site type) used in portal extensions to configure data.
URL: /mop/{site-type}sites/{site-name}/{site-layout}
Example of reading the site layout as xml for site classic.
GET /mop/portalsites/classic/portal.xml or GET /mop/portalsites/classic/portal?op=read-config-as-xml
HTTP/1.1 200 OK Content-Type: application/xml <portal-config> <portal-name>classic</portal-name> <label>Classic</label> <description>GateIn default portal</description> <locale>en</locale> ... </portal-config>
Example of exporting the site layout for site classic.
GET /mop/portalsites/classic/portal.zip or GET /mop/portalsites/classic/portal?op=export-resource
HTTP/1.1 200 OK Content-Type: application/zip [binary data]
The pages resource represents the pages of the portal. It's the data defined in the pages.xml used in portal extensions to configure data.
URL: /mop/{site-type}sites/{site-name}/pages/{page-name}
Example of reading all pages as xml for site classic.
GET /mop/portalsites/classic/pages.xml or GET /mop/portalsites/classic/pages?op=read-config-as-xml
HTTP/1.1 200 OK
Content-Type: application/xml
<page-set>
<page>
<name>homepage</name>
<title>Home Page</title>
<access-permissions>Everyone</access-permissions>
<edit-permission>*:/platform/administrators</edit-permission>
<show-max-window>false</show-max-window>
<portlet-application>
...
</page-set>
Example of reading the homepage as xml for site classic.
GET /mop/portalsites/classic/pages/homepage.xml or GET /mop/portalsites/classic/pages/homepage?op=read-config-as-xml
HTTP/1.1 200 OK
Content-Type: application/xml
<page-set>
<page>
<name>homepage</name>
<title>Home Page</title>
<access-permissions>Everyone</access-permissions>
<edit-permission>*:/platform/administrators</edit-permission>
<show-max-window>false</show-max-window>
<portlet-application>
...
</page-set>
Example of exporting all pages of site classic.
GET /mop/portalsites/classic/pages.zip or GET /mop/portalsites/classic/pages?op=export-resource
HTTP/1.1 200 OK Content-Type: application/zip [binary data]
Filtering is activated when the filter attribute is passed to an export-resource operation. The filter attribute is a multi-value attribute that is passed as request parameters of the HTTP request.
You can either include multiple filter parameters (?filter=foo:bar&filter=baz:foo-bar) or separate via ';' character (?filter=foo:bar;baz:foo-bar)
GET /mop/groupsites/platform/administrators/navigation.zip?filter=nav-uri:/administration/registry,/administration/pageManagement
GET /mop.zip?filter=site-type:!user,group
The commands included in the management component provide us the tools to perform management operations on these MOP artifacts: site layout, pages, and navigation.
The paths of the MOP resources are exactly the same as the REST URL's (of course without the URL syntax). For example the path of the homepage for the classic site would be:
[ /]% cd /mop/portalsites/classic/pages/homepage [homepage]% pwd /mop/portalsites/classic/pages/homepage
All resources/paths can be autocompleted by hitting the tab key.
Filtering is activated when the filter attribute is passed to an export-resource operation. The filter attribute is a multi-value attribute that is passed to the CLI using the --filter attribute for the export command.
export --file /tmp/mop.zip --filter site-type:portal /mop
export --file /tmp/mop.zip --filter site-type:!user /mop
The option can be specified multiple times for multiple values.
export --file /tmp/mop.zip --filter site-type:group --filter site-name:/platform/administrators /mop
Also as discussed in the Path Templates section in this document, the filter attribute can separate different path templates by the ; character.
export --file /tmp/classic.zip --filter page-name:homepage;nav-uri:home /mop/portalsites/classic
All three artifacts (site layout, navigation, and pages) are included in export by default. In other words if you don't specify their path template in the filter, the data will be included.
The SCP command can be used to export and import MOP artifacts: site layout, pages, and navigation over different hosts. The following examples will assume the portal and CLI is running at host 'example.org' with default ssh port configured to 2000.
Since the export-resource command is supported on all resources of the MOP extension, below are just some examples.
$ scp -P 2000 'root@example.org:portal:/mop/portalsites/classic' classic.zip $ scp -P 2000 'root@example.org:portal:/mop/portalsites/classic/pages/homepage' homepage.zip $ scp -P 2000 'root@example.org:portal:/mop' mop.zip
The import-resource operation is only supported at the mop resource, so for every import the path must be '/mop'.
$ scp -P 2000 classic.zip 'root@example.org:portal:/mop' $ scp -P 2000 homepage.zip 'root@example.org:portal:/mop?importMode=overwrite' $ scp -P 2000 mop.zip 'root@example.org:portal:/mop'