If you followed the tutorial Getting Started With VRSpace to install VRSpace then you ran the VRSpace server from the vrspace\bin directory. Server.jar lies in this directory, which is the file that contains all of the classes for running the server (v0.9.3: If you followed the directions for version 0.9.3 then, by default, you placed server.jar in c:\vrspace and ran the server from there). After we ran the server for the first time (and shut it down), two new files were created in c:\vrspace\bin (v0.9.3: c:\vrspace) called vrspace.cfg, and vrspace.requestLog. In addition, vrspace.db, which originally contained just a declaration for the Tomcat object, now also contains several new objects created by default (e.g. an Administrator). Go take a look at these files now to familiarize yourself with their syntax.
Our main interest here is the vrspace.cfg file, which is the main configuration file for the VRSpace server. If it is not present in the directory in which the server is invoked, it will be automatically generated:
#Autogenerated
vrspace.entry.x=0
vrspace.entry.y=10
vrspace.entry.z=0
vrspace.files.url=./pub
vrspace.files.urlprefix=http\://localhost/
vrspace.net.timeout=300000
vrspace.db.class=org.vrspace.server.db.TextDB
vrspace.port=8500
vrspace.user.class=User
vrspace.entry.mandatory=false
vrspace.server.name=nohost
vrspace.user.autocreate=true
vrspace.user.maxSessions=1
vrspace.db.url=./vrspace.db
vrspace.cfg=file\:./vrspace.cfg
vrspace.scene.filters=
org.vrspace.server.filter.ActiveClientFilter
org.vrspace.server.filter.ActiveOrOwnedTransformFilter
vrspace.checkpoint.interval=30000
vrspace.user.url=Dolphin.wrl
vrspace.checkpoint.gc=false
vrspace.requestlog.file=./vrspace.requestlog
For future reference, the file vrspace.cfg.README is located in c:\vrspace\bin (v0.9.3: download the file and save it in c:\vrspace). This configuration file has brief comments explaining each of the server properties defined above. If you want to use it as your configuration file, make a copy of it and rename the copy to vrspace.cfg (make a copy because the server rewrites the configuration file after every run and removes all those useful comments).
The VRSpace configuration file is actually a Java properties file in disguise. If you are unfamiliar with the syntax of these files please refer to the Syntax section below. Most of the properties defined in the file can be safely left to their default values except for two: vrspace.files.url and vrspace.files.urlprefix, which we will change below.
VRSpace allows users to upload files to the server at runtime (such as VRML files). The vrspace.files.url property specifies the location where the uploaded files are stored. Assuming that you installed the client in c:\vrspace\tomcat\webapps\ROOT\vrspace, a good location for published files might be in a subdirectory pub (pub stands for published). You could then set the property to:
The address may also be specified relative to the directory the server is started in, so assuming we start the server in c:\vrspace\bin, we could use:
It is important to be careful when choosing the directory to which users will upload. Don't, for example, choose c:\vrspace\tomcat\webapps\ROOT\vrspace itself as the location. If you were to do so, a malicious user could replace the VRSpace client's files (e.g., vrspace.wrl) with their own "special" copies. Whatever directory you choose, it should lie beneath the client's directory so that users can later access the file through the web server. To understand what effect setting the above property has, imagine you upload the file donkey.wrl to the server. The server knows from vrspace.files.url to save it as
The second property, vrspace.files.urlprefix, explains to the server how a user coming to your web site (let's call it www.domain.com) will request these files. In the above example, since donkey.wrl is located in the directory vrspace\pub\ beneath the web root directory, a user requesting the file would point their browser to:
The vrspace.files.urlprefix property is set to this url prefix. That is, we could set the property to:
Fortunately, the url can also be specified relative to where vrspace.html, the entrance page of the client, is located. So, if a user accesses the client via "http://www.domain.com:8080/vrspace/vrspace.html", then setting
will have the same effect as the above. In fact, it is better since if you ever move the client application, all there references to the files will automatically change. So now, go into vrspace.cfg, and set these two properties. The second choice above for each property (the relative ones) are recommended.
If you want to use the absolute addresses above and you don't have a domain name, you can replace www.domain.com with your ip address, or if you are only going to be accessing VRSpace with the computer running the server, you can replace it with localhost. If you are running the VRSpace client with a traditional web server, instead of Tomcat, the :8080 should be removed from the above urls (8080 is the default port on which Tomcat listens). See the platform specific examples below for further assistance.
Java properties files are composed of two types of lines: Comments and Definitions. Those lines beginning with a # are comments and are ignored by the program. Definitions have the syntax:
What needs to be explained is the syntax of a string. At first guess, you might write something like:
Unfortunately, : and \ are special characters to Java and must always be prefixed with a \. Thus, the preceding definition would actually be written:
Luckily, Java understands a \ and / to be the same thing when specifying urls so we can also write:
In short, when working with strings in the configuration file, replace all : with \: and all \ with /.
Supposing you installed the client in /usr/vrspace/tomcat/webapps/ROOT/vrspace.
Supposing you installed the client in c:\apache\htdocs\vrspace.
Supposing you installed the client in /usr/apache/html/vrspace.