test

Service Registry 3 2005Q4 Administration Guide

Chapter 1 Configuring and Setting Up Service Registry

This chapter describes how to configure Service Registry after you install it and how to perform other administrative tasks.

This chapter contains the following sections:

Configuring Service Registry

The Sun Java Enterprise System 2005Q4 Installation Guide for UNIX describes how to perform post-install configuration of Service Registry using default property settings for the Registry. To use custom property settings, edit the file ServiceRegistry-base/install/install.properties before you perform the configuration.

The ServiceRegistry-base location is /opt/SUNWsoar in the Solaris operating environment and /opt/sun/SUNWsoar on Linux systems.

Note –

Before you configure Service Registry, you must first install and configure Sun Java System Application Server (“Application Server”). The configuration process for Service Registry installs the Registry into an Application Server domain.

It is recommended that you install Application Server in its default location. If you installed Application Server in a non-default location, follow the instructions in Configuring Service Registry for a Non-Default Application Server Installation before you configure Service Registry.

The install.properties file contains a set of modifiable property settings. The properties that are listed in Table 1–1 are used by the installation process. Each property name has the prefix registry.install. (terminating in a period). Most of these properties set non-default ports for the Application Server domain created for the Registry.

Table 1–1 Service Registry Installation Properties

Property Name 

Description 

Default Property Value 

DomainName

Application Server domain name 

registry

ServerInstancePort

Application Server HTTP port.  

6060

ServerInstanceSecurePort

Application Server HTTPS port.  

6443

ServerJMSPort

Application Server Message Queue port 

6484

ServerIIOPPort

Application Server IIOP port 

6485

ServerIIOPSecurePort

Application Server IIOP secure port 

6486

ServerIIOPMutualAuthPort

Application Server IIOP mutual authentication port 

6487

AdministrationJMXPort

Application Server JMX port 

6488

AdministrationPort

Application Server Administrative Server port 

6489

AdministratorUserID

User name used to access Application Server Administrative Server 

admin

AdministratorPassword

Password used to access Application Server Administrative Server 

12345678

ApplicationServerKeystorePassword

Password used to access Application Server keystore 

12345678

RegistryServerKeystorePassword

Password used to access Service Registry keystore 

12345678

ProcedureTo Configure Service Registry After a Configure Later Installation Using Custom Properties

Before You Begin

To configure the Registry, you must be logged in as root or become superuser.

Steps

  1. Change to the ServiceRegistry-base/install directory.

  2. Edit the modifiable properties in the file install.properties.

    For security reasons, it is recommended that you not edit this file to change the password values. Instead, specify these values on the command line.

  3. After editing the file, run the following command (all on one line):

    On Solaris: /usr/sfw/bin/ant -f build-install.xml install

    On Linux: /opt/sun/bin/ant --noconfig -f build-install.xml install

    The ant command requires the JAVA_HOME environment variable to be set. Ordinarily, you set this variable to the following value:

    /usr/jdk/entsys-j2se

    To specify changed passwords on the command line, specify the following options to the command (all on one line):


    /usr/sfw/bin/ant -f build-install.xml
-Dregistry.install.RegistryServerKeystorePassword=passwd1
-Dregistry.install.AdministratorPassword=passwd2
-Dregistry.install.ApplicationServerKeystorePassword=passwd3 install

    The Registry configuration process creates an Application Server domain at RegistryDomain-base/domains/${registry.install.DomainName}. The default domain name is registry. The configuration process then starts the domain, deploys the Registry, and leaves the domain running.

    The Registry configuration process installs the Registry database and server keystore in the directory RegistryDomain-base/3.0. This directory is not removed when the Registry is uninstalled, so that the database can be preserved for use in a future release. The administrator has control over when and whether to remove this directory.

    The RegistryDomain-base location is /var/opt/SUNWsoar in the Solaris operating environment and /var/opt/sun/SUNWsoar on Linux systems.

  4. Review the output of the ant install command for any errors.

    If there are no errors, you can now begin using the Web Console or the Admin Tool.

ProcedureTo Enable Use of the Administration Tool

To perform Admin Tool tasks that are restricted to users with the role of administrator, you need to work around a bug by adding a JAR file to the Admin Tool manifest classpath.

Steps

  1. Make sure you are still in the ServiceRegistry-base/install directory.

  2. Copy the file soapprocessor.jar from the deployed Registry to the Registry lib directory. Execute the following command (all on one line):


    cp 
RegistryDomain-base/domains/registry/applications/j2ee-modules/soar/WEB-INF/lib/soapprocessor.jar 
../lib

  3. Run the admin.jar.manifest.fix installation target as follows:

    On Solaris: /usr/sfw/bin/ant -f build-install.xml admin.jar.manifest.fix

    On Linux: /opt/sun/bin/ant --noconfig -f build-install.xml admin.jar.manifest.fix

Administering the Application Server Domain for Service Registry

The configuration process for Service Registry by default creates an Application Server domain named registry, to which the Service Registry web application is deployed. This domain is in the RegistryDomain-base/domains/registry directory.

This location is different from the default location for Application Server domains, /var/opt/SUNWappserver/domains (Solaris) or /var/opt/sun/appserver/domains (Linux).

To administer the registry domain, you can use the Application Server Administration Console (“Admin Console”). You can use the Admin Console to start and stop the domain, view the server log, and perform other administrative tasks. See To Use the Application Server Admin Console for details.

You can also examine the server log directly. The log is in the file RegistryDomain-base/domains/registry/logs/server.log.

You can also use the asadmin command to administer the registry domain. Because the domain is not in the default location, you must specify the --domaindir option when you use asadmin commands that provide that option.

The password file for the registry domain is ServiceRegistry-base/pw.txt. Specify this password file as the argument to the --passwordfile option of asadmin commands when you administer the registry domain.

The registry domain uses a set of non-default ports so as not to cause conflicts with the default Application Server domain, domain1. Table 1–2 lists and describes these ports. For more information, see Ports in the Application Server in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide.

Table 1–2 Service Registry Domain Default Ports

Port Value 

Description 

6060 

HTTP port 

6443 

HTTPS over SSL 

6484 

Message Queue port 

6485 

IIOP port 

6486 

IIOP SSL port 

6487 

IIOP Mutual Authentication port 

6488 

JMX port 

6489 

Application Server domain administration port 

ProcedureTo Use the Application Server Admin Console

Steps

  1. In a web browser, go to the URL https://hostname:6489/.

    hostname is the system on which Application Server and Service Registry are running.

  2. Accept the certificate that is offered.

    A login page appears

  3. On the login page, type admin in the User Name field.

  4. Type the Application Server administrator password in the Password field. Use the value that you specified for the AdministratorPassword property when you configured the Registry. The default is 12345678.

  5. Click Log In.

See Also

For details on using the Admin Console, refer to the online help for the Admin Console or to the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide.

To change the logging level for Service Registry, follow the instructions in To configure log levels in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide. The property to specify in the Additional Properties area is org.apache.commons.logging.simplelog.log.org.freebxml.omar.

ProcedureTo Stop and Restart the Application Server Domain for the Registry

The configuration process for the Registry starts the Application Server domain in which the registry is deployed. After you perform certain administrative tasks, you need to stop and restart the domain. Examples of such tasks are Allowing Access to External Web Sites and Creating an Administrator.

The Admin Console informs you if you need to restart the domain. You can use the Admin Console to perform this task. If you are using the asadmin command, you can use Ant tasks to stop and start the domain.

Steps

  1. Change to the Service Registry install directory.

    cd ServiceRegistry-base/install

  2. Run the following command (all on one line):

    Solaris: /usr/sfw/bin/ant -f build-install.xml appserver.domain.bounce

    Linux: /opt/sun/bin/ant --noconfig -f build-install.xml appserver.domain.bounce

    This target stops the domain and then restarts it.

    The build-install.xml file also contains separate Ant targets for stopping and starting the Registry domain. To stop the domain, use the Ant target appserver.domain.stop. To start the domain, use the Ant target appserver.domain.start.

ProcedureTo Add Root Certificates to the Trusted Certificates in the Registry Domain

This task extends the list of trusted certificates in the Application Server registry domain.

Perform this task only if you use a third-party certificate and the root Certificate Authority (CA) certificate for the third party is not already in the Application Server truststore. Do not perform this task if you use only registry-issued certificates.

Steps

  1. Download any root certificates that you want to support. Sites that provide root certificates include the following:

  2. If necessary, use the unzip command to extract .cer files from the downloaded archive.

    Note –

    Some files have the suffix .der.

  3. Copy the .cer files to the directory ServiceRegistry-base/install/cacerts.

  4. Change to the directory ServiceRegistry-base/install.

  5. Run the following command (all on one line):

    Solaris: /usr/sfw/bin/ant -f build-install.xml install.cacerts

    Linux: /opt/sun/bin/ant --noconfig -f build-install.xml install.cacerts

    This command installs any certificates found in the directory ServiceRegistry-base/install/cacerts into the Application Server domain truststore.

    You can use the list.cacerts target to make sure that the certificates have been installed correctly.

  6. Follow the instructions in To Stop and Restart the Application Server Domain for the Registry.

Configuring Service Registry for a Non-Default Application Server Installation

The default location for installing Application Server is /opt/SUNWappserver/appserver in the Solaris operating environment and /opt/sun/appserver on Linux systems. If you installed Application Server in a different location, you must edit the file install.properties before you configure Service Registry.

ProcedureTo Edit the install.properties File

Steps

  1. In the ServiceRegistry-base/install directory, open the file install.properties in a text editor.

  2. Find the commented-out definition of the property appserver.root.dir.

  3. Remove the comment character (#) and replace the property definition with the actual location of Application Server.

  4. Save and close the install.properties file.

Next Steps

Continue with the instructions in Configuring Service Registry.

Configuring Service Registry for a Non-Default Service Registry Installation

The default location for installing Service Registry is /opt/SUNWsoar in the Solaris operating environment and /opt/sun/SUNWsoar on Linux systems. If you installed Service Registry in a different location, you must edit the file install.properties before you configure Service Registry.

ProcedureTo Edit the install.properties File

Steps

  1. In the ServiceRegistry-base/install directory, open the file install.properties in a text editor.

  2. Find the commented-out definition of the properties soar.sdk.home and soar.server.home.

  3. For each property, remove the comment character (#) and replace the property definition with the actual location of Service Registry.

  4. Save and close the install.properties file.

Next Steps

Continue with the instructions in Configuring Service Registry.

Allowing Access to External Web Sites

Any registry object can have an ExternalLink object, which specifies a URL associated with that registry object. In order for users to create ExternalLink objects, Service Registry must be able to validate the URL, and this task requires access to external web sites. If the Registry is deployed behind a firewall, you need to set a proxy configuration that allows this access.

Proxy configuration requires you to specify a web proxy host and port as Java Virtual Machine (JVM) options of the Application Server instance where Service Registry is deployed.

ProcedureTo Specify a Web Proxy

Steps

  1. Log in to the Application Server Admin Console as described in To Use the Application Server Admin Console.

  2. Expand the Configurations node.

  3. Expand the server node, server-config (Admin Config).

  4. Click JVM Settings.

  5. Click the JVM Options tab.

  6. Click Add JVM Option.

  7. In the text field, type the following (all on one line):


    -Dhttp.proxyHost=hostname.domainname -Dhttp.proxyPort=8080

    The port value is usually 8080. If the port is different in your location, specify the correct value.

  8. Click Save.

  9. Follow the instructions in To Stop and Restart the Application Server Domain for the Registry.

Creating an Administrator

The Service Registry administration tool has some tasks that only a user who is registered as an administrator can perform. In addition, an administrator might be called upon to implement life cycle changes (for example, approvals) to objects other users submit.

An administrator can also change the default access control policy (ACP). However, writing an ACP is currently a manual process that requires knowledge of OASIS eXtensible Access Control Markup Language (XACML). For details, refer to Chapter 9, “Access Control Information Model,” of ebXML RIM 3.0, especially the examples in Sections 9.7.6 through 9.7.8. See Before You Read This Book for information on how to find the ebXML RIM 3.0 specification.

ProcedureTo Create an Administrator

To register yourself as an administrator, follow these steps.

Steps

  1. Perform user registration as described in Creating a User Account in Service Registry 3 2005Q4 User’s Guide

    Remember the path name of the certificate you downloaded. The default name of the certificate file is generated-key.p12.

  2. Obtain the unique identifier of your User object as follows:

    1. Use the Web Console to perform a Basic Query, with the Object Type set to User.

    2. Click the Details link to view the User object the Registry created for you.

    3. Make a note of the Unique Identifier field value.

  3. Copy the certificate to the following location in your home directory, creating directories as needed:

    $HOME/soar/3.0/jaxr-ebxml/security

  4. Change to the directory RegistryDomain-base/domains/registry/applications/j2ee-modules/soar/WEB-INF/classes.

  5. Open the file omar.properties in a text editor.

  6. Find the definition of the property omar.security.authorization.registryAdministrators.

  7. Edit the property definition by adding a vertical bar (|), followed by the logical identifier string that you made a note of in Step 2.

    The property definition must all be on one line and must not contain spaces. After you finish, it will look something like this (all on one line):

    omar.security.authorization.registryAdministrators=
urn:freebxml:registry:predefinedusers:registryoperator|
urn:uuid:77f5c196-79de-4286-8483-8d80def3583b

  8. Save and close the omar.properties file.

  9. Follow the instructions in To Stop and Restart the Application Server Domain for the Registry.

Next Steps

To create additional administrators, you do not have to edit the omar.properties file. If you are an administrator, you can use either the Admin Tool or the Web Console to add users, and you can use the Web Console to classify the users as administrators.

Configuring the Web Console

As an administrator, you can customize some aspects of the Web Console display by editing configuration files. This section describes the following tasks:

For information about using the Web Console, see the Service Registry 3 2005Q4 User’s Guide.

Adding Predefined Queries

Service Registry includes several predefined queries, which appear in the Web Console Search form in the Select Predefined Query drop-down list. As an administrator, you can add new queries to the drop-down list that are specific to your installation of the Registry.

ProcedureTo Add a Predefined Query

Steps

  1. Use the Web Console to publish an AdhocQuery object to the Registry.

    The name and description you specify for the query will appear in the drop-down list of predefined queries. In the SQL statement for the query, specify placeholders for user-supplied data by enclosing them in pairs of single quotes, as follows:

    select * from registryobject where id = ''$lid''

  2. Make a note of the unique identifier of the AdhocQuery object and of any placeholders in the SQL statement.

  3. Change to the directory RegistryDomain-base/3.0/jaxr-ebxml.

  4. Open the file registry-browser-config.xml in a text editor.

  5. Add an entry to the registry-browser-config.xml file, using the following format. Specify a Parameter element for each placeholder in the SQL statement.

    <Query>
  <AdhocQueryRef id="unique_identifier"/>
  <Parameter parameterName="$placeholder_name" datatype="string">
    <rim:Name>
      <rim:LocalizedString xml:lang="en" charset="UTF-8" 
        value="parameter_name_in_en_locale"/>
      <rim:LocalizedString xml:lang="fr" charset="UTF-8" 
        value="parameter_name_in_fr_locale"/>
    </rim:Name>
    <rim:Description>
      <rim:LocalizedString xml:lang="en" charset="UTF-8" 
        value="parameter_description_in_en_locale"/>
      <rim:LocalizedString xml:lang="fr" charset="UTF-8" 
        value="parameter_description_in_fr_locale"/>
    </rim:Description>
  </Parameter>
  ...
</Query>

    The unique_identifier is the unique identifier of the AdhocQuery object.

    The parameterName attribute value for each parameter must come from a placeholder in the SQL statement for the query.

    The datatype attribute can have any of the following values:

    • string: The parameter appears as a text field in the Search form.

    • taxonomyElement: The parameter appears as a drop-down list in the Search form. If you specify a taxonomyElement data type, the Name and Description elements must be followed by a SlotList element that looks like this:

      <rim:SlotList>
  <rim:Slot name="domain">
    <rim:ValueList>
      <rim:Value>
      classification_scheme_or_concept_id
      </rim:Value>
    </rim:ValueList>
  </rim:Slot>
</rim:SlotList>

      The classification_scheme_or_concept_id is the unique identifier of the classification scheme or concept whose concepts (or subconcepts) must appear in the drop-down list. You must publish the classification scheme if it does not already exist in the registry.

      The slot name must be "domain".

    • boolean: The parameter appears as a checkbox in the Search form.

    If the datatype is string or boolean, you can also add a defaultValue attribute to the Parameter element to specify a default value to appear in the Search form.

    Specify localized string values for each parameter name and description for any locales you support. The parameter_name in the current locale appears as the label of the parameter in the Search form.

    Use the existing entries in the registry-browser-config.xml file as a reference.

  6. Save and close the registry-browser-config.xml file.

  7. Follow the instructions in To Stop and Restart the Application Server Domain for the Registry.

Changing the Default Query

The query that appears as the default in the Select Predefined Query drop-down list is Basic Query, which allows users to search for registry objects by name, description, and classification.

As an administrator, you can change this default to a query that is appropriate to your installation. For example, you might want the default query to be a new predefined query that you added to the Registry, as described in Adding Predefined Queries. To make this change, edit a property in a configuration file.

ProcedureTo Change the Default Query

Steps

  1. Change to the directory RegistryDomain-base/domains/registry/applications/j2ee-modules/soar/WEB-INF/classes.

  2. Open the file jaxr-ebxml.properties in a text editor.

  3. Find the definition of the property jaxr-ebxml.thin.defaultQueryPanel. By default, this property is commented out:

    #jaxr-ebxml.thin.defaultQueryPanel=

  4. Remove the comment character (#).

  5. Set the value of the property by specifying the logical identifier of the query that will be the default, as in the following example:

    jaxr-ebxml.thin.defaultQueryPanel=urn:oasis:names:tc:ebxml-regrep:query:MyQuery

  6. Save and close the jaxr-ebxml.properties file.

  7. Follow the instructions in To Stop and Restart the Application Server Domain for the Registry.

Hiding Classification Schemes

A tree structure of classification schemes appears in the following areas of the Web Console:

As an administrator, you can hide classification schemes from view if you do not want the classification schemes to be available to users of Service Registry. To hide classification schemes, define a property in a configuration file.

ProcedureTo Hide Classification Schemes

Steps

  1. Change to the directory RegistryDomain-base/domains/registry/applications/j2ee-modules/soar/WEB-INF/classes.

  2. Open the file jaxr-ebxml.properties in a text editor.

  3. Set the property jaxr-ebxml.registryBrowser.ConceptsTreeModel.hiddenSchemesList by using the following syntax. All of the property definition must be on one line and must not contain spaces.

    jaxr-ebxml.registryBrowser.ConceptsTreeModel.hiddenSchemesList=
class_scheme_id1|class_scheme_id2|...

    Specify the logical identifier of each classification scheme that is to be hidden. If you specify more than one identifier, separate the identifiers with a vertical bar (|), as in the following example:

    jaxr-ebxml.registryBrowser.ConceptsTreeModel.hiddenSchemesList=
urn:oasis:names:tc:ebxml-regrep:classificationScheme:StatusType|
urn:oasis:names:tc:ebxml-regrep:profile:ws:classificationScheme:BindingType

  4. Save and close the jaxr-ebxml.properties file.

  5. Follow the instructions in To Stop and Restart the Application Server Domain for the Registry.

Configuring the Search Results Display

By default, the Web Console displays 10 search results at a time for each query. If the search returns more than 10 results, users can display additional pages of results. As an administrator, you can modify the number of search results that appears on each page.

By default, the Web Console displays certain columns in the search results area. For each object, it displays the object type, name, description, version, and version comment. For some object types, a non-default display is configured. For example, for a ServiceBinding object, the display includes the endpoint instead of the version information. As an administrator, you can add configuration information to display non-default data for object types of your choice.

To perform each of these tasks, you edit a configuration file.

ProcedureTo Configure the Number of Rows in the Search Results Display

Steps

  1. Change to the directory RegistryDomain-base/domains/registry/applications/j2ee-modules/soar/WEB-INF/classes.

  2. Open the file jaxr-ebxml.properties in a text editor.

  3. Find the definition of the property omar.client.thinbrowser.numSearchResults:

    omar.client.thinbrowser.numSearchResults=10

  4. Change the value 10 to the value you prefer.

  5. Save and close the jaxr-ebxml.properties file.

  6. Follow the instructions in To Stop and Restart the Application Server Domain for the Registry.

ProcedureTo Configure the Columns in the Search Results Area

Steps

  1. Change to the directory RegistryDomain-base/3.0/jaxr-ebxml.

  2. Open the file registry-browser-config.xml in a text editor.

  3. Add an entry to the registry-browser-config.xml file, using the following format.

    This example configures a non-default display for Service objects.

    <ObjectTypeConfig 
    className="org.freebxml.omar.client.xml.registry.infomodel.ServiceImpl" 
    id="urn:oasis:names:tc:ebxml-regrep:ObjectType:RegistryObject:Service">
  <SearchResultsConfig>
    <SearchResultsColumn columnClass="java.lang.Object" 
      columnHeader="Object Type" columnWidth="25" editable="false" 
      method="getObjectType"/>
    <SearchResultsColumn columnClass="java.lang.Object" 
      columnHeader="Name" columnWidth="25" editable="true" method="getName"/>
    <SearchResultsColumn columnClass="java.lang.Object" 
      columnHeader="Description" columnWidth="30" editable="true" 
      method="getDescription"/>
    <SearchResultsColumn columnClass="java.lang.Object" 
      columnHeader="Status" columnWidth="15" method="getStatusAsString"/>
    <SearchResultsColumn columnClass="java.lang.Object" 
      columnHeader="Version" columnWidth="5" method="getVersionName"/>
  </SearchResultsConfig>
</ObjectTypeConfig>

    The registry-browser-config.xml provides syntax for the ObjectTypeConfig element. Use the elements that are already in the file as examples. These elements configure the default display for registry objects as well as non-default displays for ExternalLink, ExtrinsicObject, and ServiceBinding objects.

    For the most part, you can deduce the method names from the class attributes in the ebXML Registry Information Model Version 3.0 specification (see Before You Read This Book for details). The getStatusAsString method can be found in the RegistryObjectImpl implementation class. (This release of Service Registry does not include API documentation, however.)

  4. Save and close the registry-browser-config.xml file.

  5. Follow the instructions in To Stop and Restart the Application Server Domain for the Registry.

  6. To verify the reconfiguration, use the Search or Explore menu of the Web Console to display the objects whose columns you changed.

Reinstalling Service Registry

If you need to uninstall and reinstall Service Registry, perform the following tasks before you reinstall:

If you need to reinstall the Service Registry database (for example, if the database becomes corrupted), follow the instructions in To Reinstall the Service Registry Database. You do not need to uninstall the database before you reinstall it.

ProcedureTo Stop and Delete the Application Server Domain for the Registry

Steps

  1. Change to the ServiceRegistry-base/install directory.

  2. Run the following command (all on one line):

    Solaris: /usr/sfw/bin/ant -f build-install.xml appserver.domain.stop

    Linux: /opt/sun/bin/ant --noconfig -f build-install.xml appserver.domain.stop

  3. Run the following command (all on one line):

    Solaris: /usr/sfw/bin/ant -f build-install.xml appserver.domain.delete

    Linux: /opt/sun/bin/ant --noconfig -f build-install.xml appserver.domain.delete

ProcedureTo Reinstall the Service Registry Database

Steps

  1. Change to the ServiceRegistry-base/install directory.

  2. Run the following command (all on one line):

    Solaris: /usr/sfw/bin/ant -f build-install.xml install.db

    Linux: /opt/sun/bin/ant --noconfig -f build-install.xml install.db

Backing Up and Restoring the Database

The Registry uses the Apache Derby database. By default, the database is located in the directory RegistryDomain-base/3.0/data/registry/soar/.

To learn how to back up and restore the database, consult the Apache Derby documentation.

ProcedureTo Locate the Apache Derby Documentation

Steps

  1. In a web browser, go to the Apache Derby web site.

  2. Click the Manuals tab.

  3. Click 10.0 Manuals.

  4. Locate the Server & Admin Guide.

  5. Locate the sections on backing up and restoring databases.