Goal Of This Tutorial
After you finish this tutorial, you should be able to build and deploy the ogoglio system from the source repository using maven, see that the system is work properly on your local machine, and use your newly built instance of the system via the web. In addition, it shows some of the typical methods that seasoned ogoglio developers use to develop the software, if you would like to follow the well-trodden path.
What You Need To Know Before You Start
You need to know enough subversion to be able to get a copy of the sources, enough about grabbing stuff off the net to download and install some files, enough shell to know how to change environment variables and your what your PATH is, enough java to know what a java "build" is and what it looks like when it goes wrong, and enough about the web to know if a server is working or not.
Setup Your Development Machine
You'll need a copy of Sun's JDK if you don't already have it. At the current time, all ogoglio developers are using version 1.5 but it is likely to work on Java 6 as well--let us know if you get Java 6 to work! The source code of the main system requires only jdk 1.4 to compile and run, but the use of maven below implies java 1.5 so we'll assume in this document you are using 1.5. Also, be very sure that your JAVA_HOME environment is set to point to the JRE (not the JDK if you also have that installed). On my Linux development system, I have to set the JAVA_HOME variable to point "inside" the installation of the JDK:
iansmith@mediasvr:~$ echo $JAVA_HOME
/usr/local/jdk1.5.0_12/jre
You'll also need to have maven 2 installed on your machine. All the current ogoglio developers use version 2.0.7, although it is likely to work on any Maven 2 version. If you are not familiar with maven, this might be a good time to read an article or two about it, although this tutorial will try to explain maven concepts as needed (since you won't bother reading anything else before getting the system working). Be sure that your path is setup to include maven's driver program, mvn:
iansmith@mediasvr:~$ mvn --version
Maven version: 2.0.7
Java version: 1.5.0_12
OS name: "linux" version: "2.6.20-16-386" arch: "i386"
If you don't have it already, you'll need a copy of java 3d. If you running on a Mac with recent version of OS X, you can ignore this step since Apple (correctly) ships its java development configuration with java 3d installed properly. On other OSes, you'll need to download this Java extension and install it according to the directions. Ogoglio has been tested with java 3d versions 1.4 and 1.3 but is likely to work with later versions as well. The ogoglio server and clients do not expect a later version of the API than 1.3. Be very careful that you got your copy of java 3d installed in the right place, as it is easy to accidentally install it in the JDK not the JRE. You should be able to issue a shell command like this and get similar results:
iansmith@mediasvr:~$ ls $JAVA_HOME/lib/ext/{j3d*,vecmath*}
/usr/local/jdk1.5.0_12/jre/lib/ext/j3dcore.jar
/usr/local/jdk1.5.0_12/jre/lib/ext/j3dutils.jar
/usr/local/jdk1.5.0_12/jre/lib/ext/vecmath.jar
On any operating system, you should end up with binary files (the fast part of the java 3d graphics system) in your JRE's lib also. The exact files installed varies by version and operating system, but for example on linux:
iansmith@mediasvr:~$ ls $JAVA_HOME/lib/i386/libj3d*
/usr/local/jdk1.5.0_12/jre/lib/i386/libj3dcore-ogl-cg.so
/usr/local/jdk1.5.0_12/jre/lib/i386/libj3dcore-ogl.so
/usr/local/jdk1.5.0_12/jre/lib/i386/libj3dutils.so
Finally, you'll need to download some jar files from Sun that neither we or maven are allowed, for licensing reasons, to just ship to you. We recommend downloading the Java Transaction API (be sure to get 1.0.1B, not the latest version), Java Mail, and the Java Activation Framework and putting them in a directory called lib. You should then also copy your "plugin.jar" file from your JRE to this lib directory with a command like this:
iansmith@mediasvr:~$ cp $JAVA_HOME/lib/plugin.jar lib
This last jar file is the the netscape "live connect" api that allows
applets to communicate with their containing browser and web page.
Now you can run the little shell script below and maven (mvn) will know
about these APIs. You can run this script many times without a problem,
so don't worry if you break something at first.
#!/bin/bash
#java transactions (for hibernate)
mvn install:install-file -DgroupId=javax.transaction -DartifactId=jta -Dversion=1.0.1B -Dpackaging=jar -Dfile=lib/jta.jar
#live connect
mvn install:install-file -DgroupId=netscape -DartifactId=liveConnect -Dversion=1.0 -Dpackaging=jar -Dfile=lib/plugin.jar
#java mail
mvn install:install-file -DgroupId=com.sun -DartifactId=mail -Dversion=1.4 -Dpackaging=jar -Dfile=lib/mail.jar
mvn install:install-file -DgroupId=com.sun -DartifactId=jaf -Dversion=1.1 -Dpackaging=jar -Dfile=lib/activation.jar
When it works correctly, you should see one copy of this "success output" for each of the four files:
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2 seconds
[INFO] Finished at: Sun Sep 02 17:15:57 PDT 2007
[INFO] Final Memory: 2M/5M
What is Maven doing?
You can skip this section if you are not of a curious nature. If this was the first time you have ever run maven, you probably will have noticed a great many output messages something like this:
[INFO] org.apache.maven.plugins: checking for updates from central
[INFO] org.codehaus.mojo: checking for updates from central
[INFO] artifact org.apache.maven.plugins:maven-install-plugin: checking for updates from central
Downloading: http://repo1.maven.org/maven2/org/apache/maven/plugins/maven-install-plugin/2.2/maven-install-plugin-2.2.pom
2K downloaded
Maven comes with some knowlege of how to download dependencies from the internet (for example, from http://repo1.maven.org/maven2). Naturally, maven is implemented in terms of itself, so when you first use a maven plugin, it would be better called a "feature", it will attempt to fetch the latest version of the part of maven you need. Our little script above uses the maven "install" plugin, so it is fetched from a repository on the internet, and some of the output shown in the example immediately above.
All of the binaries that maven fetches, you install as jar files, or you build and then install end up a directory $HOME/.m2/repository. This is your local repository of binary data (mostly jar files and some meta-data for maven's bookkeeping). You can find the files you installed with script above by looking around in the repository like this:
iansmith@mediasvr:~/$ ls $HOME/.m2/repository/javax/transaction/jta/1.0.1B
jta-1.0.1B.jar
This repository is just a cache. If things go wrong and you want to start over, you can simply blow away the $HOME/.m2/repository directory and start again by using the small shell script above to restart your repository.
Install Tomcat 5.5
You need to make sure that you download and install version 5.5 of Apache's Tomcat. Ogoglio should work with many other servlet containers/web servers but the ogoglio developers all use version 5.5 of Tomcat and there are some deviations from this tutorial that would have be made to the maven configuration to use other versions or other servlet containers (jboss, resin, geronimo, jetty, etc).
Install mysql and create a database with a user
Ogoglio makes heavy use of a database and we recommend mysql version 5 because that is the version we use and we are sure works properly. Many developers already have a copy of this on their machines or, on linux, can easily get access to it via the package managers of most distributions. Since ogoglio uses hibernate for all of its database actions, in principle it should be possible to get ogoglio to work with almost any SQL database. We don't recommend trying to get ogoglio to work with another database on your first try at building/running.
With mysql installed and assuming you know the administrator username and password, create the new ogoglio database. We'll use root as the example administrator account for mysql and og as the name of the database:
iansmith@mediasvr:$ mysqladmin -u root -p create og
Now you need to get into the mysql shell and create the ogoglio account that can manipulate the mysql database:
iansmith@mediasvr:~$ mysql -u root -p
Enter password:
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 238
Server version: 5.0.38-Ubuntu_0ubuntu1-log Ubuntu 7.04 distribution
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
mysql> GRANT ALL PRIVILEGES ON og.* TO 'oguser'@'localhost' IDENTIFIED BY 'secret';
With that, you are ready to start being a real developer of ogoglio.
Building Ogoglio
To build ogoglio from source, you'll need to copy this file to $HOME/.m2/settings.xml. (If you are already a maven developer, you may have a file there and this should be added to it.) This files controls all the configuration options for ogoglio. You should look through and set the variables to match your development system, for example pointing cargo.tomcat.home at your tomcat 5.5 installation. The key variables to check are ogoglio.mysql.url (the part after the final slash should be the name of the database you created above), ogoglio.mysql.user, ogoglio.mysql.password (these two should much the account you created above), ogoglio.mediaDirectory (should be a path where ogoglio can store media files), and ogoglio.mediaURL (should be a URL form of the same path where ogoglio can store files). You may want to change the bootstrap account mentioned in ogoglio.bootstrapUser, ogoglio.bootstrapUserPW, ogoglio.allBootstrapUsersPW, and ogoglio.allBootstrapUsers. If you change those, be sure sure to be consistent when changing so that the pairs ogoglio.allBootstrapUsers,ogoglio.allBootstrapUsers, ogoglio.bootstrapUser, and ogoglio.allBootstrapUsersPW, ogoglio.bootstrapUserPW match. This account (and password) is an ogoglio account and will allow you to log in to the ogoglio server via the web when you get the server up.
You'll need to grab a copy of the ogoglio sources from the repository, like this:
svn co https://ogoglio.svn.sourceforge.net/svnroot/ogoglio/maven
This will take a few moments to pull over all the source files to your machine; many of these files are actually 3d models or other bits of art needed to make a reasonably functional system on your machine.
You need to go to the "master project" called ogoglio (all the subprojects have hyphenated names describing them) and we'll assume you were in /tmp when you grabbed the sources from subversion above. Let's be sure everything looks ok:
iansmith@mediasvr:/tmp$ cd maven/trunk/ogoglio
iansmith@mediasvr:/tmp/maven/trunk/ogoglio$ ls
pom.xml src
You'll note that there is only the pom.xml file that describes our project to maven, and a directory of source code. This is a guiding principle of all "mavenized" projects, only the source ever gets checked in. There are no jars in the source repository; they all live in $HOME/.m2/repository on the developer's machine and are either fetched or built from source as needed.
Using maven, you can build and test all the source code in one fell swoop. The output regarding ogoglio that you see should look something like this:
iansmith@mediasvr:/tmp/maven/trunk/ogoglio$ mvn clean install
[INFO] Scanning for projects...
[INFO] Reactor build order:
[INFO] Unnamed - com.ogoglio:ogoglio:pom:0.0.1-SNAPSHOT
[INFO] Unnamed - com.ogoglio:ogoglio-common:jar:0.0.1-SNAPSHOT
[INFO] Unnamed - com.ogoglio:ogoglio-appdev:jar:0.0.1-SNAPSHOT
[INFO] Unnamed - com.ogoglio:ogoglio-body-editor-applet:jar:0.0.1-SNAPSHOT
[INFO] Unnamed - com.ogoglio:ogoglio-test-applet:jar:0.0.1-SNAPSHOT
[INFO] Unnamed - com.ogoglio:ogoglio-viewer-applet:jar:0.0.1-SNAPSHOT
[INFO] Unnamed - com.ogoglio:dev-plugins:maven-plugin:0.0.1-SNAPSHOT
[INFO] ----------------------------------------------------------------------------
Again, if this is the first time you have run the maven tool, mvn, it may download a great many files to bring itself up to date. At the end of the process you should see a success message like this:
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1 minute 58 seconds
[INFO] Finished at: Sun Sep 02 18:35:04 PDT 2007
[INFO] Final Memory: 9M/28M
[INFO] ------------------------------------------------------------------------
i
You will probably have noticed that the integration tests briefly put up a window on your screen. This window is testing that the system can actually display a 3d space, and is this "flash" is expected and nothing to worry about. (If you are running this on a headless box and thus the test suite bombs when it tries to display this window, you can run a copy of Xvfb and set your DISPLAY variable to point at the Xvfb instance.)
Strictly speaking, you didn't need to do an "mvn clean" since this is your first build and there is nothing leftover from previous efforts, but its good practice if you have to come back to this step. The "install" phase implies compiling, testing, and installing the created jar files into your local maven repository. You can see the parent directories of these newly minted and installed jars with this code. You find it interesting to go exploring in these directories to see what information maven stores about the various projects.
iansmith@mediasvr:/tmp/maven/trunk/ogoglio$ ls $HOME/.m2/repository/com/ogoglio
dev-plugins ogoglio ogoglio-common
maven-metadata-central.xml ogoglio-appdev ogoglio-test-applet
maven-metadata-local.xml ogoglio-body-editor-applet ogoglio-viewer-applet
If Something Goes Wrong
Normally, you should see the success message above. If something goes wrong, you'll get some type of output from maven. A few key points of information may be helpful here.
- Figure out what maven sub-project (such ogoglio-server,
ogoglio-common, etc) you were building at the time of the failure. You
can do this by scrolling upward (sometimes quite a ways) until you see
a message like this:
code
[INFO]
[INFO] Building Unnamed - com.ogoglio:ogoglio-integration-test:war:0.0.1-SNAPSHOT
[INFO] task-segment: [install]
[INFO]
code
- If this was a unit test failure, you find the output of the tests in [subproject-name]/target/surefire-reports/ and this information is likely to be helpful in tracking down problems.
- If this was an integration test failure (which means it occurred in the integration-test project shown in the code above) then not only are the surefire reports likely to be helpful, but also the files tomcat5x.out and tomcat5x.log in the root of the subproject directory. These are the outputs of the tomcat server that was run to test the integration of the client and the server. Server errors are located in the two tomcat output files, client side errors are in the surefire reports. However, almost any time there is a server failure, some response gets sent back to the client (such as a "500 Internal Server Error") that causes it to fail also. When in doubt, try to solve the server problem first.
Booting The Ogoglio Server And Deploying The Web Application
We will assume you have now built and tested all the code and that you continue to work in /tmp. For this task you'll need to open two more shell windows, which we will call the "boot" window and the "tail" window. In both of these go to the directory that is the home of the master project, such as /tmp/maven/trunk/ogoglio in our above examples. In the boot window, you will be using maven to boot up a copy of tomcat, like this:
iansmith@mediasvr:/tmp/maven/trunk/ogoglio$ mvn -Pboot-server cargo:start
This will eventually end up with a message like this:
[INFO] [cargo:start]
[INFO] Press Ctrl-C to stop the container...
tomcat is now running and you can now iconify this window because not much exciting is going to happen here in the rest of the tutorial. However, it is vital that you understand that can reach the newly booted server (assuming you kept your $HOME/.m2/settings.xml file unchanged from the example) via http://127.0.0.1:8080/. For some reasons related to cookies, trying to access this server as http://localhost:8080/ will work just enough to convince you it's ok, then break your heart. You must access the server with the exact same URL you put in your settings.xml file. The instance of tomcat that is running is fully configured and running in /tmp/tomcat5x, as mentioned by the $HOME/.m2/settings.xml file. At this point, this server has only one web application installed in it, one used by the maven infrastructure itself, called cargopc. You can see any and all installed web applications like this:
iansmith@mediasvr:/tmp/maven/trunk/ogoglio$ ls /tmp/tomcat5x/webapps/
cargocpc cargocpc.war
The war file is a standard format for java web applications--which is really just an archive file. The unpacked version of the war file is in the directory that bears its name.
To monitor the state of tomcat's output, you should use your other shell window, the "tail" window, to do this:
iansmith@mediasvr:/tmp/maven/trunk/ogoglio$ tail -f tomcat5x.out
Under normal conditions this "tail" window will never show stack backtraces or other serious errors. If they are present, it's probably worth looking carefully at this window's output (or the underlying tomcat5x.out file in your ogoglio master project directory) to try to see what's wrong.
Let's try deploying the ogoglio-server web application to our running tomcat instance. This is referred to as a "hot deploy" by ogoglio developers (keep up on your lingo!).
iansmith@mediasvr:/tmp/maven/trunk/ogoglio$ cd ../ogoglio-server
iansmith@mediasvr:/tmp/maven/trunk/ogoglio-server$ mvn -Phot-deploy cargo:deploy
After some work, maven should respond with a message like this:
[INFO] [stalledLocalDeployer] Deploying [/tmp/maven/trunk/ogoglio-server/target/ogoglio-server-0.0.1-SNAPSHOT.war] to [/tmp/tomcat5x/webapps]...
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 35 seconds
[INFO] Finished at: Sun Sep 02 18:54:17 PDT 2007
[INFO] Final Memory: 10M/19M
[INFO] ------------------------------------------------------------------------
The "local deployer" line indicates that the war for this application has been sent to the tomcat server running in your other windows. Since tomcat watches /tmp/tomcat5x/webapps for changes, shortly after you see this build message you'll see your tail window going crazy with messages as tomcat brings up the new web application. You can see the effect in the webapps directory:
iansmith@mediasvr:/tmp/maven/trunk/ogoglio$ ls /tmp/tomcat5x/webapps
cargocpc cargocpc.war og og.war
Assuming everything has gone ok this far, you can point your browser at http://127.0.0.1:8080/og and you should see the ogoglio welcome banner (or "coming soon" if the welcome banner hasn't been implemented yet!).
Working On The Server Code Proper
The previous example we booted an instance tomcat and used the "hot-deploy" to push new server code (in a war file) to the running tomcat. This is the basic way to send the server code to be tested with a browser. If you are developing server-side code or (gasp) fixing bugs, you go into the ogoglio-server project, make your src code changes in src/main/java/com/ogoglio, and then use a maven command at the top-level directory like this:
iansmith@mediasvr:/tmp/maven/trunk/ogoglio-server$ mvn clean install
This builds all the sources, runs the server's unit tests, and (if everything went ok) builds a war file that you can run the integration tests on. This war file is put in the maven repository as a war file so it can be accessed by other projects, if referenced. You see this with:
iansmith@mediasvr:/tmp/maven/trunk/ogoglio-server$ ls ~/.m2/repository/com/ogoglio/ogoglio-server/0.0.1-SNAPSHOT/
maven-metadata-local.xml ogoglio-server-0.0.1-SNAPSHOT.war
ogoglio-server-0.0.1-SNAPSHOT.pom
A bit tricky, though, is the hidden fact that some of the unit tests destroy the database's data. They do this so the tests can be sure of the system state when performing tests, but any running server instance has no idea what has occurred "behind it's back." If you return to your web browser connected to a previously run server, you may get strange results. (See the next section for how to easily reconstruct the data you want to work with.) You can take a bit more dangerous shortcut if you are working solely on the web UI, e.g. the HTML and javascript files in src/main/resources/siteTemplates:
iansmith@mediasvr:/tmp/maven/trunk/ogoglio-server$ mvn -Phot-deploy compile war:war cargo:deploy
This runs the compile phase, builds the war file and deploys it to the running server but skips running the tests. We don't recommend doing this for server-side java code, although it's likely to work in the short term because avoiding the unit or integration tests is a recipie for disaster. Trust us, we know. This should only be used for tweaking the look and feel of ogoglio's web UI. Without the shortcut it can be quite tedious to go through the full test regime to get a change of a pixel here or there.
Minor Secret
The web UI for ogoglio that is contained in src/main/resources/siteTemplates understands Velocity templates. If you put velocity directives like this in ogoglio's html files
#parse("header.vm")
they will be correctly expanded, assuming of course you have a "header.vm" file in that directory also. This expansion runs during the "compile" phase of building the server. After that point, the HTML used for ogoglio's UI is frozen and doesn't change. At no point does the server ever "generate" HTML for consumption by any client--it only servers up static content or speaks XML via it's web API.
Returning to our discussion of the server's java code, if you have successfully passed the server's unit tests (with 'mvn clean install' above) you should run the integration tests. During this process, a real copy of tomcat gets launched and (your presumably new) server code is deployed to it. The integration test suite behaves like a client: it uses real HTTP calls on the server code to insure that the new code hasn't broken anything. You can run the integration test by switching to the integration test project's top level directory and doing this:
iansmith@mediasvr:/tmp/maven/trunk/ogoglio-integration-test$ mvn clean install
In fact, this doesn't actually "install" anything much in your maven repository. We use the "clean install" idiom in every directory to mean "do everything you need to do." As we said above, the integration tests will actually put a window on your screen briefly. It should now be more clear why: that test is testing that a client application can actually connect to space on the server with an applet.
Committers
The ogoglio project's developers are pretty serious about thorough
testing; our testing constantly improves. If you want to be a commiter
on the project, we'd ask that as you fix bugs or add features please
add unit and functional (integration) tests that show that you have
fixed the bug or correctly implemented the new feature.
Working With 3-D Objects and Spaces During Development
Ogoglio comes with a tool for batch uploading of templates (3-D models and their scripts) and automatically creating spaces on a running server. You can see this in action with:
iansmith@mediasvr:/tmp/maven/trunk/ogoglio-server$ mvn og:populate
When you run this command you should see a bunch of output like this as it does its work (if you don't, check and be sure that your server is running--'mvn -Pboot-server cargo:start' in ogoglio's master project directory):
[INFO] Uploading template #9 to http://127.0.0.1:8080/og/
[INFO] Created template from EamesLoungeChair.obj [9 -> 5]
[INFO] Uploaded support file:EamesLoungeChair.mtl
[INFO] Uploaded support file:wood11.jpg
This output shows that the various bits of the Eames Lounge Chair were uploaded and although it was listed as template number 9 in the src/main/resources/populate directory, its template ID on the running server is 5.
The "og:populate" command in maven is configured to look look in the directory src/main/resources/populate for files and directories that have names that might be spaces or templates. If it finds them, it uploads them to a running server. It is careful to try to not upload templates that have the same name as ones already present on the server. It does this based on the names and dates, so you'll need to touch the templates object file, thus updating its last changed time, before the upload process will destroy the one on the server and replace it with your newer version . The contents of a template directory looks like this:
iansmith@mediasvr:/tmp/maven/trunk/ogoglio-server$ ls src/main/resources/populate/template-1
Moon.jpg Moon.js Moon.mtl Moon.obj
The template when it is uploaded will not be numbered 1. The ogoglio server will chose the template's ID based on its state. as we saw in the example above with the lounge chair changing to ID number 5. The resulting template will be named "Moon." The ".obj" file has the 3-D model in a textual form, the ".mtl" is the materials used in the model, the ".jpg" is a texture, and the ".js" file is javascript code associated with that template. These are the primary file types used by the system itself; some of the templates supplied with ogoglio have other types of files in their directories like (.blend or .3DS) that can be used to edit the model with tools like blender or 3-D Studio. These are just for your convenience, the template uploader during og:populate will ignore them.
Also allowed in the src/main/resource/populate directory of the ogoglio-server project are spaces. Let's look at a space document that will get uploaded when we do "mvn og:populate":
iansmith@mediasvr:/tmp/maven/trunk/ogoglio-server$ more src/main/resources/populate/space-1
<space ownerusername="library" sealevel="0.0" simid="1"
displayname="Sitting" maxguests="0" displaysea="false" spaceid="1"
published="true">
<thing templateid="9" rz="0.0" ry="0.0" rx="0.0" rw="1.0"
scalez="1.0" displayname="EamesLoungeChair" scaley="1.0"
templateowner="library" scalex="1.0" possessionid="1" thingid="1
"
z="-5.0" y="0.0" x="-18.0" ownerusername="library" />
[several more thing elements elided for clarity]
</space>
When og:populate runs, it creates a space on the server with the name "Sitting." Again the server's final ID for the new space will be of it's own choosing, it's not likely to be '1' as this document's filename might suggest. However, the uploader does change the templates used in the final, resulting space document to be sensible with respect to the template numbers in the directory names. In other words, you can write this space document as if the template numbers were indicated correctly by the directory names, such as '9' above in the space document. It will get changed to the correct number at the time the space is constructed, which might be '5' as we saw in our prior discussion of the Eames Lounge Chair.
If you go visit this 'Sitting' space on your running server, you should see 5 chairs in the space, all arranged so that they are facing you when you enter the space (just spin around with the left/right arrow keys to see them). You can change the chairs properties (like orientation and location) in the resulting space by changing properties in the space-1 document, deleting the space with the ogoglio web UI, and re-running "mvn og:populate."
This process can also be done in reverse. This means that you can use the ogoglio server's web UI to manipulate objects in a space, chosing and arranging the objects in the space to get them the way you want. Then, you have to expose (ta-da!) that ogoglio is really a web application! You do this by going to a URL that looks like this
http://127.0.0.1:8080/og/space/1?children=true
This URL asks the server to respond with its space document for space number 1. You can figure out a space's number by choosing to edit the space from the web UI and looking at the URL your browser goes to. It will look like this and the space's ID will be pretty obvious.
http://127.0.0.1:8080/og/spaceEditor.html?spaceID=1
When you go to the URL to get the space document, you should use your browser's "save as" function to save the resulting XML into a file named "/tmp/reverse.xml". This filename is controlled, like everything about maven in the pom.xml file in the root directory of the ogoglio-server project. You can then do the following to ask for this, newly saved, space document to be "converted" to use the templates in your populate directory.
iansmith@mediasvr:/tmp/maven/trunk/ogoglio-server$ mvn og:reverse
This command will output a new space document into the src/main/resources/populate directory in which the server's "true" mapping has been reversed back to the ones you see on disk. If you think about the Eames Lounge Chair in prior examples, it is contained in a directory called "template-9". We saw that when we uploaded the chair the true template number was 5 on the server, but our space document space-1 could use the 9 to indicate which template it was referring to and the upload would be "patched" to use the server's number. When doing a reverse, a space document is patched the other way, so that the "real" space document you just downloaded into /tmp.reverse.xml will be copied into the populate directory of the source code and will refer to the numbers of the templates in that same directory.
If you have been following this carefully, you should realize that this whole process of og:populate and og:reverse allows you to create data--spaces and templates--that persist across clearing the database.
Comments