Embedded HTTP server

Wandora has a built-in simple http server that can be used to browse a topic map with any web browser or share a topic map.

Note that this server is not designed for large scale web applications, you should use Wandora Piccolo framework and a real servlet container such as Apache Tomcat for that. See Setting up Wandora Piccolo server for more information.

You can configure several different services on the built-in server. These provide different methods of access to the open topic map. These include browsing the topic map through HTML pages, a SOAP based web service access, an RSS feed, a special service for Wandora Drupal extras and a service for the Wandora Firefox plugin. These are explained in more detail below.

Configuring the HTTP server

To configure the server, select the Server menu and choose Server settings. The server should work in port 8898 with default settings and allow anonymous but local only connections.

Option	Description
Auto start	Check this option to have the HTTP server start automatically whenever you start Wandora.
Port	The port used by the server.
Local only	Check this to only allow local connections. If this is checked, you will most likely need to use the loopback address (127.0.0.1 or localhost) to be able to connect. It is recommended that you either keep this checked or otherwise limit access to the server for example with a firewall. The service specific settings have a similar option. If the global local only option is set then all services are only available through local connection regardless of their settings. If the global option is not set, then the service specific settings are used.
Use SSL	If this is checked, the server will use SSL encryption. This option does not work out of the box. You will need to setup the certificate and encryption keys first. This is done using the keytool utility that should be in bin directory of your Java Development Kit. For example: keytool -genkey -keystore storefile -keyalg RSA After you have generated the certificate you need to run java with the following parameters: -Djavax.net.ssl.keyStore=storefile -Djavax.net.ssl.keyStorePassword=password
Server path	The path that contains the service configuration files. You will need to completely restart Wandora after changing this.

In addition to the global server settings, each service has their own settings. Some of these options are common to all services.

Option	Description
Enabled	Use this to enable or disable this service.
Local only	Check this to only allow local connections. See the server wide similar option for more details.
User	You can provide a user name and password required to login to the service. Note that these are stored in plain text in the options file. Also, unless you use the SSL option, they are also sent in plain text through the net.
Password	See User above.
Handler	The Java class that handles this service. Leave blank for the default handler.

Depending on the chosen handler, there may be other service specific options too. These are explained below.

Starting the server

After you have configured the server you can start it by selecting Server menu and choosing Start server. You can also click the icon in lower right corner. This icon will also indicate server status. Red circle means that server is disabled, green means that the server is running, bright green means that the server handled a request less than one second ago.

If you checked the Auto start option, the server will start automatically whenever you start Wandora.

Services

A service is an output module in Wandora's embedded HTTP server. By default Wandora's embedded HTTP server has services:

• axis
• drupal_atom
• plugin
• rss
• topic

You can configure services with Wandora application using menu option Server > Server settings.... You can also edit services directly in resources/server where each service has it's own folder. To apply manual changes you need to restart Wandora application. Each service is independent from others and services are parallel. If service is enabled, you can access the service with it's URL. The URL used to access services is of form http://host:port/servicename. For example, the HTML browser access (service named topic) at localhost and the default port can be accessd with URL http://localhost:8898/topic. Depending on the service, you generally can add service specific paths or parameters to the service URL. Next chapters describe each default service in Wandora's embedded HTTP server.

HTML browser access (topic)

This service provides a human friendly HTML access to the current topic map. HTML service name is topic. On default settings service URL is

http://localhost:8898/topic 

This will open the same topic that is currently open in the Wandora application itself. To see other topics, use get parameter topic with the subject identifier of the topic you would like to see. For example

http://localhost:8898/topic?topic=http%3A%2F%2Fwww.wandora.org%2Fcore%2Fschema-type

Generated HTML pages contains links to all other related topics using this link format allowing very easy browsing of the topic map. Image below shows Schema type topic served by the this service.

This service uses Apache velocity to serve the pages. This means that it can also be used to server pages in other formats than HTML. The template used to build the pages can be changed in the service specific options. This template should be in the templates directory under the service specific directory. You can also place any static content needed for the pages in the static directory. You do not need to add the static in the path, just add the file name after the service name. For example http://localhost:8898/topic/wandora_logo.gif for the Wandora logo at the lower part of the page.

This is also the default handler for services unless something else is specified in the service specific options.

SOAP web service access (axis)

This service provides a SOAP based web service for the topic map. Service name is axis. You can get the WSDL file from

http://localhost:8898/axis/services/TopicMapService?wsdl .

You can also use the web service with just HTTP GET method without sending the SOAP content in POST. For example

http://localhost:8898/axis/services/TopicMapService/getTopic?si=http%3A%2F%2Fwww.wandora.org%2Fcore%2Fschema-type&full=true 

Just add the method name after TopicMapService/ and the parameters needed for the method as GET parameters. You can also get the response in JSON format by if you use the outputType parameter and pass "application/json/badgerfish". For example

http://localhost:8898/axis/services/TopicMapService/getTopic?si=http%3A%2F%2Fwww.wandora.org%2Fcore%2Fschema-type&full=true&outputType=application/json/badgerfish

Drupal access (drupal_atom)

This service provides an Atom feed for the Wandora Drupal extras module. This service uses the default service handler, see notes at above #HTML browser access (Topic) for more details. Service name is drupal_atom. To access the feed on default settings use URL

http://localhost:8898/drupal_atom

Wandora Firefox and Thunderbird plugin access (plugin)

This service provides access for Wandora Firefox plugin. See the plugin page for more details.

RSS feed (rss)

This service provides an RSS feed of the instances of the currently open or specified topic. Service name is rss. To access the feed on default settings use URL

http://localhost:8898/rss

Service uses the same default handler as the HTML service but with a different template. See notes at #HTML browser access (Topic) for more details.

Setting up new services (output modules)

Wandora reads all services from folder resources/server. This folder contains one folder for each parallel output module. By default these output modules are:

• axis
• drupal_atom
• plugin
• rss
• topic

Each service folder should contain at least config.xml specifying options for the output module. For example default service topic contains config.xml:

<?xml version="1.0" encoding="UTF-8"?>
<options>
  <enabled>true</enabled>
  <template>viewtopic.vhtml</template>
  <user></user>
  <password></password>
  <localonly>true</localonly>
</options>

Configuring embedded HTTP server in Wandora application allows you to change all options in config.xml. If you decide to edit configuration file manually, you need to restart Wandora application in order to apply changes. However, you can't create nor delete services with Wandora application. Service creation and deletion requires manual actions. To set up yet another parallel service for Wandora's embedded HTTP server follow next steps

• Create a folder in resources/server. Folder name will be service name, you access the service using it's name. For example, if you create a folder my-output in resources/server, your service is called my-output and you have to access the service with URL

http://127.0.0.1:8898/my-output

• Create a configuration file config.xml in the service directory. The configuration file is important, as Wandora application recognizes services only if they have valid configuration file. Enter appropriate XML elements and content to the configuration file. You can always take a look at the existing services if you are unsure about required options.
• Create all other files such as templates, graphics etc. required by your output service. Typically, if you create a template based output service such as topic, you need to create at least one Velocity template file that generates output for the service.
• Restart Wandora application.
• Start Wandora's embedded HTTP server and try to access the service. Remember that the service must be enabled.

Known Issues

It seems that Windows Vista maps localhost to an IPv6 address "::1" which may cause problems various problems unless you change all references to localhost to 127.0.0.1 or some other IP address. You can change this behavior by editing C:\Windows\System32\drivers\etc\hosts file and making localhost resolve to 127.0.0.1, note that you will need to do this as an administrator user.