System Requirements

JDK 1.4.0 or above Note: The Xalan that comes with JDK 1.4.x is a beta version which does not work properly with the Apache XML security library. To override the built-in Xalan of JDK 1.4.x, you need to copy xalan.jar from the misc/lib directory in the ebxmlrr distribution (available in the download section ) to <JDK_1.4.x_home>/jre/lib/endorsed. If the directory does not exist, you have to create it. If you use Tomcat 4.1, or 4.2, you additionally need to copy xalan.jar, xercesImpl.jar and dom.jar from the ebxmlrr/misc/lib directory to the <Tomcat_home>/common/endorsed directory. That is because the Tomcat startup script sets the location where java looks for endorsed libraries to its own directories.

Tomcat 4.0.4 or above . We have tested the deployment to all versions from 4.0.4 to 5.0 of Tomcat. Other servlet engines may work, but we have not tested the deployment to other platforms. For instructions on how to configure Jetty follow this link .

A relational database that supports SQL-92 syntax. We have tested the deployment to PostgreSQL 7.1 ( How to setup PostgresSQL ) and Oracle 9i.

Downloading the Required Files

To obtain the latest stable releases you need to download source packages from the download section :

  • Windows Platform: Download file ebxmlrr-server- <release_version> -src.zip and extract using WinZip utility.

  • Unix Platform: Download file ebxmlrr-server- <release_version> -src.tar.gz and extract using

    gunzip -c ebxmlrr-server- <release_version> -src.tar.gz
    | tar xvf -

The source package includes all dependent libraries that are required.

Binary packages are not available currently. However, the source distribution comes with all sources already built and ready to deploy.

Alternatively, you may check out the latest source tree from CVS repository . CVS checkout provides you with latest bug fixes and features. However latest CVS bits may be less stable than a packaged release.

Setting up environment variables



Variable
Description
Unix Example
Windows Example
JAVA_HOMEThe home directory for JDK installation.~/j2sdk1.4.0c:\j2sdk1.4.0

Make sure the Java runtime environment executable (e.g. <JAVA_HOME>/jre/bin/java.exe for Windows) and Java compiler executable (e.g. <JAVA_HOME>/bin/javac.exe for Windows) are in the environment variable PATH.

Configuration

Copy <ebxmlrr_home>/conf/ebxmlrr.properties into your home directory (e.g. C:\documents and settings\<username> in win2k). <ebxmlrr_home> is the directory storing the extracted files of the packaged release or the CVS source tree.

The file ebxmlrr.properties allows you to configure ebxmlrr. The usage of the configuration properties are as follows. For the properties related to file path, use "/" as path separator in Windows.





https://sourceforge.net/forum/forum.php?forum_id=310837


Property
Description
ebxmlrr.home The home directory for storing repository and keystore. By default, it is set to <your_home_directory>/ebxmlrr if you keep this entry commented.

Note: Make sure you use forward slashes '/' as path separator on windows platform.

Note: If you run Tomcat as NT service in Windows NT/2000/XP, by default the logon ID used to run Tomcat is "LocalSystem", whose home directory is C:\Documents and Settings\Default User. You need to change the logon ID to your ID and restart the service.

ebxmlrr.interfaces.soap.signedResponse Whether the registry server should sign the response. According to the specification, the response from registry must be signed. However, signing the response will lengthen the response time.
ebxmlrr.persistence.rdb.databaseURL The URL for connecting the database via JDBC. If you use Cloudscape, you don't need to change it. You may need to consult the documentation of your database to find out the syntax of the URL.
ebxmlrr.persistence.rdb.databaseDriver The fully qualified class name of the JDBC driver. If you use Cloudscape, you don't need to change it.
ebxmlrr.persistence.rdb.databaseUserThe user for connecting the database.
ebxmlrr.persistence.rdb.databaseUserPasswordThe password for connecting the database.
ebxmlrr.persistence.rdb.useConnectionPooling Whether database connection pooling is enabled. We highly recommend you to enable connection pooling. Usually a database will be collapsed if too many connections are opened. Connection pooling can restrict the number of connection opened, and, the connection time will be much shorter. However, if you use Cloudscape (it only supports one connection), you should not enable it.
ebxmlrr.persistence.rdb.pool.initialSize The initial size of database connection pool. It only takes effect if useConnectionPooling is true.
ebxmlrr.persistence.rdb.pool.maxSize The maximum size of database connection pool. It only takes effect if useConnectionPooling is true.
ebxmlrr.persistence.rdb.pool.connectionTimeOut The time out of connecting database. If this period of time has been elapsed but a connection to database cannot be made, a error response will be returned to the client. This feature enables the client will not wait the response forever.
ebxmlrr.persistence.rdb.ExternalLinkDAO.checkURLs Whether the validity of ExternalLink 's HTTP URL should be checked. If the response code from the server at the URL is smaller than 200 or larger than 299, the URL is considered as invalid.
ebxmlrr.persistence.rdb.ServiceBindingDAO.checkURLsWhether the validity of ServiceBinding 's HTTP URL is checked.
ebxmlrr.repository.homeThe root directory of repository.
ebxmlrr.repository.quota The quota limit of submitted items in repository. All the users have the same quota. It is in mega bytes.
ebxmlrr.security.keystoreFile The keystore used by the registry to find the certificates of the registered users.
ebxmlrr.security.keystorePasswordThe password of the keystore.
ebxmlrr.security.userCacheSize A user cache is to hold the users recently accessed so the server needs not always load the user 's details from database whenever a user submit a request. This property is to set the number of users in the cache.
ebxmlrr.security.validateCertificates It controls whether the certificate is verified that it is issued by most trusted certificate authority (so-called trust anchors).
ebxmlrr.security.trustAnchors.keystoreFile The keystore for storing the certificates of trust anchors. The factory value is the one with file name "cacerts" inside JDK/JRE. Set the path of JDK/JRE appropriately in this value.
ebxmlrr.security.trustAnchors.keystorePassword The password of trust anchors keystore. If you did not change the password of the trust anchors keystore inside JDK/JRE before, the password should be "changeit".
ebxmlrr.security.trustAnchors.keystoreType The type of the trust anchors keystore. The one inside JDK/JRE should be of type "jks".
ebxmlrr.repository.repositoryManagerClassThe package qualified Class to be instantiated as the implementation of the RepositoryManager pluggable interface.
ebxmlrr.security.ignoreInvalidHeaderSignaturesIt control whether the server should ignore errors during signature verification of a SOAP Message. This is useful if you are getting false positive signature verification errors for some reason
ebxmlrr.security.ignoreInvalidPayloadSignaturesIt control whether the server should ignore errors during signature verification of a SOAP Message payloads. This is useful if you are getting false positive signature verification errors for some reason
ebxmlrr.persistence.rdb.skipAssociationConfirmationIt control whether the server should skip confirmation checks when an Association is submitted. This is useful if you want high performance and submit large number of associations.
ebxmlrr.persistence.rdb.skipReferenceCheckOnRemoveIt control whether the server should skip checking if an object is being referenced when removing it. This is useful if you want high performance.
ebxmlrr.security.authorization.useXACMLIt control whether the server should use the XACML based access control policy feature. This is useful if you want more advanced fine-grained Role Based Access Control (RBAC).
ebxmlrr.security.authorization.defaultACPIt configures the default Policy file used by the XACML based access control policy feature. This is useful if you are a registry administrator and wish to customize the default Access Control Policies for your registry.
ebxmlrr.security.authorization.registryAdministratorsIt configures the set of users that should be assigned the role of RegistryAdministrator and its associated "superuser" like privileges. This is useful if you are a registry administrator and want to add addition registry administrator.

Building From Source

The distribution comes ready to run, with the software already compiled and packaged into jars. However, it can be built directly from the CVS repository or the source distribution using Apache ant as described next.

To build from source follow these steps:

  1. change current directory to <ebxmlrr_home>.
  2. type "build compile". If you are using Unix/Linux and Korn shell is available, type "./build.sh instead". Also on Unix platforms you may need to make build.sh executable by typing "chmod 755 build.sh".
The source code will be compiled and the binary will be in <ebxmlrr_home>/build/lib/classes.

Deployment to Tomcat

Shutdown Tomcat first.

Make a copy of <ebxmlrr_home>/build.properties.template and rename it to build.properties. Keep this in the same directory. Note that this file is to control the deployment parameters only. The runtime parameters are set in ebxmlrr.properties in your home directory.

Open build.properties with a text editor and edit this two properties:

  • catalina.home = Tomcat 's home directory. In Windows environment, Tomcat path may include white spaces (e.g. c:\Program Files\Apache Tomcat 4.0\) and things will still work if you leave spaces.
  • ebxmlrr.repository.home = The directory for storing repository item. In any cases, you should make sure that its value is equal to the value of ebxmlrr.repository.home entry in ebxmlrr.properties.

We have only packaged the JDBC driver for PostgreSQL into the distributions. If you use other databases such as Oracle 9i, you need to download yourself and put it in lib directory (for binary distribution) or misc/lib directory (for source distribution or checkout from CVS).

Type "build deploy" in <ebxmlrr_home>. It will create a Web application "ebxmlrr" in Tomcat and copy the compiled classes into the <tomcat_home>/webapps/ebxmlrr/WEB-INF/classes. The directory for storing repository item will be created automatically if it does not exist.

If you are not using PostgreSQL as the database, remember to edit database connection properties in ebxmlrr.properties. The database connection properties in build.properties is irrelevant after deployment to Tomcat.

If you want to enable debugging output, set the environment variable CATALINA_OPTS to -Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog . You can set the variable e.g. in the Tomcat startup script. See SimpleLog and Commons Logging for more options that you can configure.

Restart Tomcat.

Bootstrapping the Database

Configuring database connection properties

You are recommended to use PostgreSQL version 7.1 or above as the database. You can follow the instructions on this

page

to setup PostgreSQL on Windows. Setup a database with name "registry".

Open the text file <ebxmlrr_home>/build.properties, which is created in section 6. Note that build.properties only takes effect at installation time. The runtime parameters are specified by ebxmlrr.properties in the home directory. You should be able to find the following properties:

jdbcDriver

dbURL

dbUsername

dbPassword

jdbcClassName

Change them accordingly. The meaning of the properties in the above lines are as follows:





Property
Description
Example
jdbcDriverPath of the JDBC driver jar PostgreSQL:

jdbcDriver=${build.home}/lib/postgresql.jar

Oracle:

jdbcDriver=C:/oracle/ora92/jdbc/lib/classes12.jar

dbURLURL for connecting the database via JDBC PostgreSQL:

dbURL=jdbc:postgresql://localhost:5432/registry

Oracle:

dbURL=jdbc:oracle:thin:@localhost:1521:test

dbUsernameUsername for connecting the databasedbUsername=ebxmlrr
dbPasswordPassword for connecting the databasedbPassword=ebxmlrr
jdbcClassNameThe fully qualified name of the JDBC driver PostgreSQL:

jdbcClassName=org.postgresql.Driver

Oracle:

jdbcClassName=oracle.jdbc.driver.OracleDriver

Loading the sample data

Change current directory to <ebxmlrr_home>.

Make sure that tomcat has been restarted.

Type "build genKeys" to generate private keys for signing the requests. It will also generate certificates for authenticating the predefined users.

Set ebxmlrr.persistence.rdb.ExternalLinkDAO.checkURLs and ebxmlrr.persistence.rdb.ServiceBindingDAO.checkURLs to false because the demo data may contain some invalid URLs. But according to the specifications, the validity of the URLs should be checked. After going through all the setup procedures, you should set them to true.

Type "build createDemoDB". The predefined users, standard classification schemes (ISO 3166 and NAICS) and some other demo data will be loaded into the database after running it.

If you want to clean the database, you can type "build cleandb". It will delete all the tables for ebxmlrr in the database.

Testing your own installation

Now we are going to submit a request to your own installation.

In <ebxmlrr_home>/build.xml, we can see a target "test":

If the registry server is installed in somewhere other than localhost or port, replace url=http://localhost:8080/ebxmlrr/registry/soap accordingly. It will send a AdhocQueryRequest to the server. The request file, SQLQuery_1.xml, is located in <ebxmlrr_home>/misc/samples.

Type "build test". Open <ebxmlrr_home>/response.xml. It is the response from your registry server. You can see the content of response.xml similar to this:

If your installation is successful, you can see that the responses encloses a RegisryResponse element with status = "Success".

Finally you should subscribe to the mailing list ebxmlrr-tech@lists.sourceforge.net by filling the form at http://lists.sourceforge.net/lists/listinfo/ebxmlrr-tech . Any update will be sent to this mailing list.

If you have any comments or queries, please feel free to send a email to ebxmlrr-tech@lists.sourceforge.net

.