{section}
{column}

h1. The beginning installation:

At the beginning, you +don't need to configure anything+ for the Petals Webconsole, you just need to install the _war_ on your

favourite Java web server.

*At the first run* of the Petals Webconsole if you haven't uncomment the following server in the _webconsole.xml_:
{code:lang=xml|title=Default webconsole.xml file}<ns:Servers xmlns:ns="org.ow2.petals.tools.webconsole.xmlbeans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="org.ow2.petals.tools.webconsole.xmlbeans webconsole.xsd ">
    <ns:Server port="7700" login="petals" password="petals" host="localhost" domain="default" name="0">
        <installedrmicomponent>false</installedrmicomponent>
        <rmiport>1091</rmiport>
        <rmicontext>RMIComponentContext</rmicontext>
    </ns:Server>
</ns:Servers>{code}
This file is used +to save the referential topology+ where you are connected, we will see later how to synchronize current topology and referential topology,

If any server is declared the following screen is displayed:

!empty-first-connection.png|thumbnail!
This screen precise to you that no server was found and therefore propose the following attempt to connect to one.
If you click on "+Try a new server connection+" the following form is displayed:

!try-new-connection.png|thumbnail!

In this form you must provide four parameters:
# The Petals server +host+ like localhost, "_192.168.1.108, 127.0.0.1 ..._"
# The Petals JMX server +port+ like "_7700, 7701, 7702 .._."
# The Petals JMX server +login+ like "_petals_".
# The Petals JMX server +password+ like "_petals_".

These previous parameter are often available in the _topology.xml_ of your
Petals ESB container or at the start of you container, by the following
String: _service:jmx:rmi:///jndi/rmi://192.168.1.108:7702/jmxRmiConnector_
{note:title=Host resolution}{_}You can either provide an IP address or a hostname, but check to your network administrator if address resolution is available. If you have many Petals nodes spread across different sub networks._{note}

If when you submit the form the connection is available, the following screen are displayed:

!success-server-connection.png|thumbnail!
This message informs you that the connection attempt has succeeded.

After that you can see the server where you are connected:

!first-connection-server-view.png|thumbnail!
{info}Take attention to the following information, now, when you are connected to one server doesn't say that the server is registered in the referential topology file.{info}

We will see in the next chapter the difference between the *real-time topology* view and the *referential topology persisted* in _webconsole.xml_ file.

h1. Two different topology management:


h2. Concept explanation:


h3. First management, "real-time topology view":

This view is represented by the server menu to the left of the Petals Webconsole

interface:

!realtime-topology-view.png|thumbnail!

All server displayed in this menu, are the available or unavailable of the current
topology where you are connected. This menu is a *real-time* view and is based
on the topology returned by the _active server connection_. One connection
establishment is performed for +each server+ of the list in order to check, if the
server is available or not. This view give to you a real-time vision, of the current
domain where you are connected and



h3. Second management, "referential topology file":

This management, is represented by the server list found in referential file:

!synchonized-referential-view.png|thumbnail!

The webconsole.xml file allow you to persist server informations, which you can try
many connections, edit properties, view details ...
Two different actions allow to add server in this file, you can manually add one server
by clicking on "_add server_" button. This click display to you a server form, where you can
provide server connection parameters in order to define a new server connection.
!add-server.png|thumbnail!

The second method to add many server in the referential topology is to click on "synchronize"

button, that allow the Webconsole to add current recovered servers by the real-time topology

into the _webconsole.xml_ file. this perspective is more scope in order to synchronize the servers

of your domain, for then you can connect without necessarily knowing the server parameters.


!synchronized-topology.png|thumbnail!




h2. Practical explanation:


h3. "real-time topology view" utilization:

The real-time topology view utilization is very easy thank to the server menu which represent it \!

You only have to click on +available+ server (which are not coloured in *gray*), to perform one server

switching. For example:

Here you are on server 0 and you haven't no recovered endpoints

!server-switching-0.png|thumbnail!
If you need to display the endpoints list view of server 1, you just have

to click on the "server 1" in the real-time topology view (the left menu).

!server-switching-click.png|thumbnail!
After the previous clicking the server 1 endpoints list is displayed:

!server-switching-1.png|thumbnail!
You can see two recovered endpoints in the server 1 list.


h3. "referential topology file" utilization:

This referential view utilization is assured by the server list,

displayed in "management server" page. This list allows to

you to delete, edit, add, ... server, and synchronize the referential

topology with the current real-time toplogy by adding all recovered

servers. The user have the possibility to edit server attributes,

for example if hostname is returned by the real-time topology and

the name resolution isn't available. The user can change the host

attributes and provide the linked IP address of the server.

Moreover if the user have edited server attributes and if he performs

a "synchronize" the server informations is merged and local server

attributes is keeped, in order to don't overwrite the changes made by

Webconsole user.


You can also access to this view by clicking on "_Select one server where the connection will be established_"

button, displayed in the *welcome* Webconsole page.

!6.png|thumbnail!

In the Petals Webconsole you can find several interesting points like:
* Server configuration.
* Remote component configuration.
* General Webconsole properties.




{column}
\\
{column:width=350px}
{panel}{toc}\\ {panel}\\
{column}\\
{section}

h1. Server configuration clarification

Petals Webconsole contain an automatic mechanism that it allows to try to connect to a server declared into the webconsole.xml file,

this file is located into /WEB-INF/classes/webconsole.xml and its associated XML schema (webconsole.xsd).

h3. Server connection configuration through Webconsole interface

By clicking on the following button:

!Manage-connection-menu.png|thumbnail!

&nbsp;&nbsp;

You can access in the Petals Webconsole the management view of servers declared into webconsole.xml, management

functionalities available are:
* Create new server.
* Delete old server.
* Modify declared server.
* Switch the current server connection.

You can add a new server by clicking on _Add server_ in the server management view:

!add-servers.png|thumbnail!


&nbsp;&nbsp;

This action displays to you the server creation form:

!8.png|thumbnail!



For the moment just stay focused on the _general server properties_ because the _RMI component_
_properties_ part will be addressed in the +Remote component configuration+ part of this documentation.

In the general server properties part the following server parameters must be defined:
* The hostname or ip address of the new Petals server.
* The JMX connection port of the server.
* The JMX login connection of the server.
* The JMX password connection of the server.



When you submit the form a new server should be created in _server list_ and this server should be also _added into the_

_webconsole.xml_, if it isn't +already defined+.

&nbsp;&nbsp;

You can also modify server properties by editing the desired server (by clicking on details icon: !loupe.png|thumbnail! in the server list):

!details-servers.png|thumbnail!

&nbsp;&nbsp;

After clicking on the link you return to the creation server form but this time in order to change +current server+
+properties+ and not to create a new server.

&nbsp;&nbsp;

Another good feature is to allow to remove an old server if it isn't necessary for the moment in the server list,
this removal can be performed by clicking on the following icon: !Delete-server.jpg|thumbnail!



(!) *Warning:* If you have stacktrace due to failed connections, please verify if at least one declared server
in the webconsole.xml can be acceded. Other careful point, we recommend to you that don't keep this
configuration file empty (keep at least one server in order to allow the webconsole to try a connection, even
if the Petals ESB node is down).

You can also switch or connect to one server of the list, by only clicking on the connection icon:

!connect-servers.png|thumbnail!

It's useful in order to change of current Petals Domain.

When you try a new server connection and if the connection is available, the Petals Webconsole
allows you to save the complete recovered topology.

!persist-topology.png|thumbnail!


h3. Server connection configuration through webconsole.xml

You can also perform the previous features (create, delete, modify ... server) directly in the webconsole.xml under

*/WEB-INF/classes/webconsole.xml*. Just modify XML attributes to perform server properties modification, or

add/remove _Server_ XML element in order to add/remove a server in configuration file.
{code:title=webconsole.xml}<ns:Servers xmlns:ns="org.ow2.petals.tools.webconsole.xmlbeans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="org.ow2.petals.tools.webconsole.xmlbeans webconsole.xsd ">
<ns:Server port="7700" login="petals" password="petals" host="localhost">
<installedrmicomponent>true</installedrmicomponent>
<rmiport>1099</rmiport>
<rmicontext>RMIComponentContext</rmicontext>
</ns:Server>
</ns:Servers>{code}

(i) *Information*: To aims of keeping the webconsole.xml configuration file +valide+, you can use the associated XML schema

webconsole.xsd located in the same location.

h1. Remote component configuration


h3. RMI configuration through Webconsole interface

In the same form where you create or modify one server configuration, you can set


a configuration for RMI component that allow to establish a remote communication

between Petals Webconsole and Petals ESB.

RMI component must be declared into the webconsole.xml configuration file and

started in you Petals ESB node, where it is declared.

!modify-server-properties.png|thumbnail!


In this form part dedicated of the RMI component properties declaration two fields can be filled:
* The RMI context, it must be the *same* as that the petals-se-rmi component
deployed on the Petals node.
* The RMI port, it must be *consistent with* that declared in the petal-se-rmi.

&nbsp;&nbsp;

If you have declared one RMI component in the configuration file but if isn't available on the

Petals node, you can thank to the form's checkbox (petals-se-rmi component enabled)

disabled it in the Webconsole while keeping it declared:

!Disabled-checkbox-form.png|thumbnail!


h3. RMI configuration through webconsole.xml


You can also perform the previous features for the RMI component directly in the webconsole.xml under,

as the same way that server declaration. Just modify the XML according to the webconsole.xsd scheme.
{code:lang=xml|title=Webconsole.xml RMI declaration}<Server ... >
<installedrmicomponent>false</installedrmicomponent>
<rmiport>1099</rmiport>
<rmicontext>RMIComponentContext</rmicontext>
</Server>{code}
{code:lang=xml|title=Webconsole.xsd RMI template} <xs:complexType name="_Server">
<xs:sequence>
<xs:element name="installedrmicomponent" type="xs:boolean" maxOccurs="1" minOccurs="0"/>
<xs:element name="rmiport" type="xs:int" maxOccurs="1" minOccurs="0"/>
<xs:element name="rmicontext" type="xs:string" maxOccurs="1" minOccurs="0"/>
</xs:sequence>

...

</xs:complexType name="_Server">{code}

(i) *Information*: To aims of keeping the webconsole.xml configuration file +valide+, you can use the associated XML schema

webconsole.xsd located in the same location.

&nbsp;&nbsp;

(!) *Caution*: the following message may means that a RMI component isn't _declared_ in the webconsole.xml, or _disabled_

in this configuration file:

!automatic-remote-component-installation1.png|thumbnail!


&nbsp;&nbsp;

(!) *Caution*: the last following message may means that a RMI component isn't _deployed_, isn't started on the Petals ESB node where

it is declared or simply the associated port _don't match_:

!automatic-remote-component-installation2.png|thumbnail!
{info:title=Automatic remote componet installation}_&nbsp;_ _&nbsp;_

If you click on "*Install remote component*", the Petals Webconsole automatically install a remote component packaged with the current version.

The current version is packaged with the petals-se-rmi for remoting communication to Petals ESB. _&nbsp;_

_The Webconsole_ transfers you to the installation interface and automatically select *URL* installation and provide the url which match

the packaged petals-se-rmi that will be installed, when you confirm the installation on the current Petals ESB node.
{info}
!automatic-remote-component-installation3.png|thumbnail!

The previous screen displays the automatic remote component installation (you have just to submit the installation form).

h1. General properties file presentation

Petals Webconsole contain a file where several general properties can be configured,&nbsp; some of these

are really useful and need a correct configuration and not hang lightly.

h3. The general.properties

Several properties affect the Webconsole configuration instead other affect displayed error messages.

h4. Repository setting
{code:title=Repository property}# --- Cache control of the RestResourcesServlet ---#
cache-control=private, max-age=60{code}
This property allows to define cache parameters like control, age ... *for uploaded files* by the Petals webconsole

Parameter examples:
* 'private' meaning for cache-control header value:

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; \*&nbsp;&nbsp;&nbsp; Can be cached only by single-user caches, such
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; \*&nbsp;&nbsp;&nbsp; as in a browser; must not be cached by multiuser
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; \*&nbsp;&nbsp;&nbsp; caches in proxy servers.

* 'max-age=60' meaning for cache control header value:

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; \*&nbsp;&nbsp;&nbsp; Serve from the cache only until the
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; \*&nbsp;&nbsp;&nbsp; specified number of seconds since the original
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; \*&nbsp;&nbsp;&nbsp; request has elapsed.

You can found more informations at [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html]

h4. Table access right settings
{code:title=Access right settings}# --- Access rights for administration tab ---
access.rights.administrator=true

# --- Access rights for test tab ---
access.rights.tester=true

# --- Access rights for monitoring tab ---
access.rights.supervisor=true{code}
These properties allows to displayed or not each tab in the Petals Webconsole

h4. Distributed setting
{code:title=Distributed installation setting}distributed.installation=false{code}
This property disallow local file upload for artefact installation, but why ?

Because if *loadbalacing* between several web server is active, you cannot

predic on which server the artefact will be uploaded. Set to true this

property in order to force user to use +URL+ instead LOCAL installation,

because in distributed Webconsole deployment perfom artefact installation

by URL is more consistent in this _kind of environment_.

h4. Cleaner setting
{code:title=Cleaner property}cleaningworker.laptime=120000{code}
The previous property allows to set the *lap time* for the workers/cleaners of remote connections,

the value is in milli-seconds. The purpose of these workers is to _clean_ and _release_ unused JMX

connections +establish with Petals ESB+, in the connection pool into Petals Webconsole.

h4. Logger setting

The Webconsole _use log4j implementation_ for application logger. You can set the

logging level for each package that you like, example:
{code:lang=xml}<logger name="org.ow2.petals.tools.webconsole" additivity="false">
<level value="error" />
<appender-ref ref="stdoutVerbose" />
</logger>

<logger name="org.ow2.petals.tools.webconsole.services.utils" additivity="false">
<level value="debug" />
<appender-ref ref="stdoutVerbose" />
</logger>{code}
You can precise the +package+ that you target by "*name*" attribute of the logger "*node*" example "_org.ow2.petals.tools.webconsole, org.ow2.petals.tools.webconsole.services.utils, ..._"

and you can precise the +logging level+ with the "*value*" attribute of the "*level*" node example "_error, debug, ..._"


h4. Error message settings
{code:title=Error message properties}number_format_error=Number format error
unknow_host_error=Unknow host error
petals_service_error=Petals service error
petals_console_error=Petals console error
user_action_error=User action error
configuration_error=Configuration error
sax_error=Sax exception error
parser_configuration_error=Parser configuration error
factory_configuration_error=Factory configuration error
wsdlexception_error=WSDL exception error
malformed_url_error=Malformed url error
ioexception_error=IO exception error
uri_syntax_error=Uri syntax error

file_not_found_error=File note found error
rmi_server_configuration_error=Rmi server configuration error
illegal_argument_error=Illegal argument error
class_loader_error=Class loader error
configuration_file_error=Configuration file error
selected_endpoint_error=Selected endpoint error
transformer_error=Transformer error
transformer_factory_configuration_error=Transformer factory configuration error
messaging_error=Messaging error
download_attachment_error=Download attachment error
form_field_error=Form field error{code}
All these previous properties allow to modify displayed error message titles in Webconsole interface, when each

king of error occurred.

These error message titles may be modified only by the Petals Webconsole Administrator if a more explicit message should be displayed

to Petals Webconsole users (or if the title isn't correctly understandable).