This document describes how to install and deploy XStreamDB.
XStreamDB install package is provided in an easy to use jar file. The installation jar file is named like this: xstreamdb<ver>_<platform>.jar
where <ver> is the version number of the XStreamDB product. As of the writing of the guide, the current version is "32". This is actually version 3.2 but the decimal point is not used in the <ver> portion of the jar file name.
where <platform> can be "win", "linux" or "mac" depending on the target operating system you selected when downloading the product.
The installation is started by opening a command window, changing to the location of the downloaded jar file and entering the following, modified for your platform:
java -jar xstreamdb32_<platform>.jar
Example: if you are installing onto a Windows system, then you would enter:
java -jar xstreamdb32_win.jar
Once the installation is complete, you will notice the following directory structure under your chosen location.
The license file contains a serial number that is required for XStreamDB Server to run. The Server will not start if the serial number is not valid. If you require a new serial number, contact Bluestream Database Software Corp. Send an email message with your request to mailto:sales@bluestream.com .
Typically the license file is populated during installation by entering the serial number (which was sent to you via email) on the serial number entry screen. If this step was skipped, or if you need to place a new serial number in the license file, here is what you do.
Once the new serial number has been correctly placed in the serialnum.txt file, the XStreamDB Server will start successfully.
In order to run XStreamDB you must start the server process first, then you can run your client process. An example client process is the XStreamDB Explorer application. If on windows, and you created shortcuts you can use those shortcuts.� Otherwise,� to run directly:
Passwords can be changed as needed via the Explorers Configuration tab. On the left hand side, there is a tree display of system features, one of which is USERS . Expanding the Users node displays all of the currently defined User Ids. Right-clicking on a User Id will present a menu which includes the Change Password option.
The XStreamDB Client library is deployed separately from of the XStreamDB Server process. For example, in some cases you may deploy the server on a separate machine from the client.
When the XStreamDB Client library is deployed, it is deployed within a user's process. This user process is typically one of the following:
In order for a user's process to use the XStreamDB client libraries, that process must be able to find the XStreamDB jars. As well, that process must set the location of the XStreamDB client home to access configuration information such as logs, property files and server connection parameters.
| Client Configuration |
|
Before attempting to start a Client process, do the
following one time only:
1. Change to the {InstallDir}/Client/Explorer directory. 2. Run the config.sh script to assign executable permission to the shell scripts in this directory as well as to scripts located in the Client/samples subdirectories. This example assumes Bash is the shell being used: bash ./config.sh |
| Console Sample Environment |
|
Prior to attempting to run the sample scripts in
Client/samples/console, do the following once, to build the Java classes:
1. Change to the {InstallDir}/Client/Explorer directory. 2. Execute the setenv.sh script to prepare the environment to run the sample scripts, including the build script: . ./setenv.sh 3. Execute the build.sh script to generate the sample Java classes. ./build.sh 4. Once the console classes have been built, the scripts can be run. The first script must be ./runGenerateDB.sh This generates a loaded database with sample documents for use with the other console sample scripts. 5. After the console sample database has been created and populated, other sample scripts will run successfully; for example: ./QueryAll.sh This script retrieves all 100 of the sample documents used in the console sample. Note that the setenv.sh script must be run once in any command window, prior to any sample script being invoked. |
The configuration options described here are optional.
In Windows, for example, this can be set by using the command:
set XDB_CLIENT_HOME=C:/XStreamDB/Client
Assuming that C:/ is your {InstallDir}. To make this setting permanent in Windows you can set XDB_CLIENT_HOME using the Windows menus selections:
Start, Settings, ControlPanel, System, Advanced, Environment Variables
<Servers>
<Server name = "MyServer" host = "localhost" port = "1223"/>
</Servers>
The ' host ' attribute may either be a Host Name as shown above, or it can be a Host Address as shown here:
<Servers>
<Server name = "DocumentServer" host = "192.57.233.19" port = "1223"/>
</Servers>
If you wish to connect to an XDBServer running on another port you may either add a new configuration tag to the XML file directly, or use the Explorer login screen to do it for you. This configuration file supports multiple <Server/> entries which is especially useful if your client machine is going to be accessing multiple XStreamDB servers.
Deployment of a standard Java application relies on the required configuration discussed above: set the classpath to each of the six jars in "{InstallDir}/XStreamDB/Client/lib" to find the jars and set xdb.client.home to "{install dir}/XStreamDB/Client" .
When your web application uses the XStreamDB Client libraries it is necessary to set the classpath to the XStreamDB client libraries and to set the xdb.client.home java system property to the XStreamDB client home. The main mode of deployment of web applications described here is the standard J2EE WAR file.
When accessing XStreamDB from a web application your web application must find the XStreamDB jar files and it must find the XStreamDB client configuration information. As a standard approach we recommend you use WAR files to deploy your WebApp and that the WAR file contain in its lib directory the 6 client jars listed above. Since the lib directory will be scanned automatically these jars will be found without modifying your WebServer's classpath.
Below are instructions for making the XStreamDB client library accessible from a web application, or Servlet:
public void init(ServletConfig servletConfig)
{
...
String path = "/WEB-INF";
ServletContext ctx = servletConfig.getServletContext();
String home = ctx.getRealPath(path);
System.setProperty("xdb.client.home", home);
...
}
This property must be set prior to issuing any calls to the
XStreamDB client API.
Server Deployment is simpler than client deployment since the server runs in its own process. To deploy the server on a separate machine simply copy the "{InstallDir}/XStreamDB/Server" directory to the separate machine in some directory of your choice (hereinafter called ServerInstallDir). and then run the server using {ServerInstallDir}/Server/bin/runServer.bat" (Windows) or {ServerInstallDir}/Server/bin/runServer.sh" (Linux or Solaris).
| Special Linux/Solaris Server Configuration |
|
Before attempting to start the Server, do the following once
only:
1. Change to the {ServerInstallDir}/Server/bin directory. 2. Run the config.sh script to assign executable permission to the runServer.sh script (which assumes Bash is the shell being used): bash ./config.sh |
The server listen port is set by changing a setting in this file:
{ServerInstallDir}/Server/conf/XDBServer.prop
The properties are:
The XStreamDB Server may optionally be installed as a Windows Service. This method of installation ensures that the XStreamDB Server will be properly started and stopped by the operating system whenever it is started and stopped.
| Note: the Server/service/ReadMe.htm file has more detailed information on running the XStreamDB Server as a service. |
These instructions explain how to install XStreamDB as a service:
:set XDB_SERVER_HOME=C:\XStreamDB\Server
set XDB_SERVER_HOME=D:\Programs\XStreamDB\Server
The XStreamDB Server should now be running as a service. You can verify that it is working by checking the current Server/log file which should contain an entry stating that the Server has started and this entry should possess a current time stamp.
Alternatively, you can go to the Client/samples/console directory and use some of the scripts to issue XQuery statements against the running XStreamDB Server.
WebDav comes preconfigured with XStreamDb. The starting war name is xrwebdav.war
Bluestream Content Management WebDAV server Version 1.0 Build: 2005-03-10T15:30:32Z
It is often necessary to change the context name for your WebDav web application. The default context is xrwebdav.war. One reason to change the context is so all your web links start with a prefix of your choosing. We recommend that you use a prefix called "xdbres". As well, if you are using the Bluestream XdbWeb application, you will want to use the same context for that web application as well - "xdbres". In order to have two web applications with the same context name, you will need two instances of the web server. Here we describe how to configure the Tomcat instance included with XStreamDB to use xdbres instead of xrwebdav for the context name.� Note, we assume if you also configure XdbWeb to use xdbres, that XdbWeb will run in a different instance of Tomcat.
Bluestream Content Management WebDAV server Version 1.0 Build: 2005-03-10T15:30:32Z
HTTP digest security is in effect for WebDAV. Because of this you will be prompted for a username and password when you access WebDAV. A good client will cache this information to avoid re-prompting for authentication.
WebDAV is an extension to the http protocol that allows a WebDAV client to access resources located on a WebDAV server. Example WebDAV clients are XMLSpy, Microsoft Web Folders and XMetaL. The XStreamDB WebDAV server is a java servlet, running on a WebServer, that accesses the XStreaWebDAVmDB native XML database server. The resources being served up by the XDB WebDAV servlet are the documents and binary resources stored in the XStreamDB database server.
Before resources can be served by XStreamDB, however, it is necessary to configure the resource categories and their resources using the XStreamDB Explorer Resources tab.
With the standard setup the WebDAV root is at http://{host}/xdb/resource. If you wish to link to other XML documents from within an XML document, then you have to decide on a linking strategy. The most common linking strategy is the "root relative link". When using a root relative link you refer to other documents by first specifying /xdb/resource followed by the {DatabaseName}/{RootName}[/{more categories}...]/DocumentName. See the section called "Rich Edit" in the documentation.
http://localhost:8080/xrwebdavfor Server and press Browse button.
Note: that the host address, 'localhost', and port number used above, '8080', are typical default values. You should change these values as needed to reflect your Servlet container installation.
Another way to view the documents hosted by the XDB WebApp is to use a WebDAV compliant folder to display them.
To open the XDB WebApp in a Windows WebDAV folder:
http://localhost:8080/xrwebdavPress Next , and then, Finish on the next dialog.
You must have Corel XMetaL version 3.1.3.058 or later to use XStreamDB WebDAV. The XMetaL editor is very well suited to visualizing XML document data as standard documents. In fact, this document is authored using XMetaL and the Journalist.xsd schema. In order to load a document using XMetaL you must mount it as a microsoft web folder as described above. Once mounted as a WebFolder files are simply opened using the standard file/open menu from within XMetaL.
The journalist schema is a subset of the more extensive DocBook XML vocabulary. The journalist schema and the macros necessary to view journalist documents ship with XMetaL right out of the box.
Last Modified Date: Monday, March 22, 2004 10:45:54 AM