Embedded HTTP server

From WandoraWiki
(Difference between revisions)
Jump to: navigation, search
(→‎Mobile browser access (mobile))
(→‎Services)
 
(33 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
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.
+
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. The server is based on the [[Wandora modules framework]].  
−
 
+
−
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 ==
 
== 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.
+
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. Screen capture below demonstrates actual server settings dialog window in Wandora application.
 +
 
 +
 
 +
[[Image:modulesserversettings.png|center]]
 +
 
  
 
{| cellspacing="0" cellpadding="5" border="1"  
 
{| cellspacing="0" cellpadding="5" border="1"  
Line 31: Line 33:
 
  |-
 
  |-
 
  | valign="top" | Server path
 
  | valign="top" | Server path
−
  | valign="top" | The path that contains the service configuration files. You will need to completely restart Wandora after changing this.
+
  | valign="top" | The path that contains the service configuration files. By default the path is '''resources/server/'''. You will need to completely restart Wandora after changing this.
 +
|-
 +
| valign="top" | Log level
 +
| valign="top" | The lowest level of log messages that are printed to the console. Defaults to ''warn'', meaning that only messages of level warning or error are printed, purely informative messages are not.
 
  |}
 
  |}
  
−
In addition to the global server settings, each service has their own settings. Some of these options are common to all services.
+
In addition to the settings dialog, some server settings can be configured by modifying the configuration xml files of the server itself and of each service. The structure of these files is described on the [[Wandora modules framework]] page. The server configuration file is in '''resources/server/baseconfig.xml'''. All services are in subdirectories under '''resources/server''' and their '''config.xml''' configuration files are in the directory of the service.
−
 
+
−
{| cellspacing="0" cellpadding="5" border="1"
+
−
|-
+
−
! Option
+
−
! Description
+
−
|-
+
−
| valign="top" | Enabled
+
−
| valign="top" | Use this to enable or disable this service.
+
−
|-
+
−
| valign="top" | Local only
+
−
| valign="top" | Check this to only allow local connections. See the server wide similar option for more details.
+
−
|-
+
−
| valign="top" | User
+
−
| valign="top" | 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.
+
−
|-
+
−
| valign="top" | Password
+
−
| valign="top" | See ''User'' above.
+
−
|-
+
−
| valign="top" | Handler
+
−
| valign="top" | 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 ==
 
== Starting the server ==
Line 67: Line 49:
 
== Services ==
 
== Services ==
  
−
A service is an output module in Wandora's embedded HTTP server. By default Wandora's embedded HTTP server has services:
+
By default Wandora's embedded HTTP server supports service modules:
  
−
* axis
+
* '''topic''' - [[HTML service module]]
−
* drupal_atom
+
* '''mobile''' - [[Mobile HTML service module]]
−
* plugin
+
* '''rss''' - [[RSS feed service module]]
−
* rss
+
* '''axis''' - [[SOAP web service module]]
−
* topic
+
* '''drupal_atom''' - [[Drupal service module]]
−
* mobile
+
* '''plugin''' - [[Firefox and Thunderbird plugin service module]]
 +
* '''xtm''' - [[XTM topic map service module]]
 +
* '''jtm''' - [[JTM topic map service module]]
 +
* '''rdf''' - [[RDF service module]]
 +
* '''graphml''' - [[GRAPHML service module]]
 +
* '''screencast''' - [[Screencast service module]]
 +
* '''flash_graph''' - [[Flash graph service module]]
 +
* '''timeline''' - [[Timeline service module]]
 +
* '''googlemaps''' - [[Google Maps service module]]
 +
* '''d3graph''' - [[D3 graph service module]]
 +
* '''d3wordcloud''' - [[D3 word cloud service module]]
 +
* '''d3partition''' - [[D3 partition service module]]
 +
* '''d3tree''' - [[D3 tree service module]]
 +
* '''d3matrix''' - [[D3 matrix service module]]
 +
* '''layer''' - [[D3 layer visualization]]
 +
* '''sameas''' - [[SameAs service module]]
  
−
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.
+
Individual services can be configured by modifying their '''config.xml''' file in their service directory. Each service has its directory under '''resources/server'''. You will need to restart Wandora application after modifying the xml configuration files. The structure of the xml configuration files is described in [[Wandora modules framework]].
  
−
=== HTML browser access (topic) ===
+
If service is enabled, you can access the service with it's URL. The URL has a form '''http://host:port/service-path'''. For example, the HTML service module (named as '''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.
  
−
This service provides a human friendly HTML access to the current topic map. HTML service name is '''topic'''. On default settings service URL is
+
== Setting up new service modules ==
  
−
http://localhost:8898/topic
+
Wandora reads all services from folder '''resources/server'''. This folder contains subdirectories for module bundles. Generally each module bundle contains one service but they can also be configured to contain several services. In any case the whole module bundle and its services are specified in the '''config.xml''' file in the module bundle directory. The structure of the xml configuration file is described at [[Wandora modules framework]].
  
−
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
+
To create a completely new module bundle and service, follow these steps.
  
−
http://localhost:8898/topic?topic=http%3A%2F%2Fwww.wandora.org%2Fcore%2Fschema-type
+
* Create a folder in '''resources/server'''. Folder name will be used when accessing the service. For example, if you create a folder '''my-service''' in '''resources/server''', your service is called '''my-service''' and you have to access the service with URL
  
−
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.
+
http://127.0.0.1:8898/my-service
  
−
[[Image:Embedded_http_server_example.gif|center]]
+
* Create a configuration file '''config.xml''' in the service directory. The configuration file is important as Wandora application recognizes services only if they have a valid configuration file. Enter appropriate XML elements and content to the configuration file. It is probably a good idea to use an existing configuration file from one of the default services as a basis. The bundle in the directory '''topic''' is a good example for a service that serves information about a single topic for each http request.
 +
* Create all other files such as templates, graphics etc. required by your service. Generally, if you create a template based output service such as '''topic''', you need to create at least one Velocity template file.
 +
* Restart Wandora application.
 +
* Start Wandora's embedded HTTP server and try to access your brand new service. Remember that the service must be enabled.
  
−
This service uses [http://velocity.apache.org/ 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 <nowiki>http://localhost:8898/topic/wandora_logo.gif</nowiki> for the Wandora logo at the lower part of the page.
+
== Known Issues ==
  
−
This is also the default handler for services unless something else is specified in the service specific options.
+
It seems that Windows Vista maps localhost to an IPv6 address "::1". To solve the problem change all references from '''localhost''' to '''127.0.0.1''' or to actual 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. Or you might just access address '''127.0.0.1''' instead of '''locahost''' with your WWW browser.
  
−
=== Mobile browser access (mobile) ===
+
== See also ==
  
−
This service provides an endpoint for mobile devices such as iPhone, iPad, Android etc. The service is based on [http://jquerymobile.com/ Mobile JQuery]. Service generates HTML representations out of topics. HTML representation is created with Apache Velocity template engine. Module's access point is
+
* The Embedded HTTP server works on the [[Wandora modules framework]], see that page for more details about setting up and configuring module bundles and services.
−
 
+
* [[Setting up Wandora Piccolo server|Wandora Piccolo]] is a similar older framework but has been deprecated in favour of the modules framework.
−
http://127.0.0.1:8898/mobile
+
* Wandora user can also view services of embedded HTTP server with the [[Webview]] panel.
−
 
+
−
=== 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 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 chapter ''HTML browser access (topic)'' for more details. Service name is '''drupal_atom'''. To access the feed on default settings use URL
+
−
 
+
−
http://127.0.0.1:8898/drupal_atom
+
−
 
+
−
Note that this service is only *one* solution to publish Wandora content with Drupal. Another solution is to use the SOAP web service access (axis) described above. This solutions is also discussed at documentation of [[Wandora Drupal extras]] module.
+
−
 
+
−
=== 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://127.0.0.1:8898/rss
+
−
 
+
−
Service uses the same default handler as the HTML service but with a different template. See notes above at chapter ''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 actual 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. Or you might just access address '''127.0.0.1''' instead of '''locahost''' with your WWW browser.
+
__NOTOC__

Latest revision as of 12:44, 20 December 2014

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.

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. The server is based on the Wandora modules framework.

[edit] 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. Screen capture below demonstrates actual server settings dialog window in Wandora application.


Modulesserversettings.png


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. By default the path is resources/server/. You will need to completely restart Wandora after changing this.
Log level The lowest level of log messages that are printed to the console. Defaults to warn, meaning that only messages of level warning or error are printed, purely informative messages are not.

In addition to the settings dialog, some server settings can be configured by modifying the configuration xml files of the server itself and of each service. The structure of these files is described on the Wandora modules framework page. The server configuration file is in resources/server/baseconfig.xml. All services are in subdirectories under resources/server and their config.xml configuration files are in the directory of the service.

[edit] 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.

[edit] Services

By default Wandora's embedded HTTP server supports service modules:

Individual services can be configured by modifying their config.xml file in their service directory. Each service has its directory under resources/server. You will need to restart Wandora application after modifying the xml configuration files. The structure of the xml configuration files is described in Wandora modules framework.

If service is enabled, you can access the service with it's URL. The URL has a form http://host:port/service-path. For example, the HTML service module (named as 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.

[edit] Setting up new service modules

Wandora reads all services from folder resources/server. This folder contains subdirectories for module bundles. Generally each module bundle contains one service but they can also be configured to contain several services. In any case the whole module bundle and its services are specified in the config.xml file in the module bundle directory. The structure of the xml configuration file is described at Wandora modules framework.

To create a completely new module bundle and service, follow these steps.

  • Create a folder in resources/server. Folder name will be used when accessing the service. For example, if you create a folder my-service in resources/server, your service is called my-service and you have to access the service with URL 
http://127.0.0.1:8898/my-service
  • Create a configuration file config.xml in the service directory. The configuration file is important as Wandora application recognizes services only if they have a valid configuration file. Enter appropriate XML elements and content to the configuration file. It is probably a good idea to use an existing configuration file from one of the default services as a basis. The bundle in the directory topic is a good example for a service that serves information about a single topic for each http request.
  • Create all other files such as templates, graphics etc. required by your service. Generally, if you create a template based output service such as topic, you need to create at least one Velocity template file.
  • Restart Wandora application.
  • Start Wandora's embedded HTTP server and try to access your brand new service. Remember that the service must be enabled.

[edit] Known Issues

It seems that Windows Vista maps localhost to an IPv6 address "::1". To solve the problem change all references from localhost to 127.0.0.1 or to actual 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. Or you might just access address 127.0.0.1 instead of locahost with your WWW browser.

[edit] See also

  • The Embedded HTTP server works on the Wandora modules framework, see that page for more details about setting up and configuring module bundles and services.
  • Wandora Piccolo is a similar older framework but has been deprecated in favour of the modules framework.
  • Wandora user can also view services of embedded HTTP server with the Webview panel.


Retrieved from "http://wandora.org/w/index.php?title=Embedded_HTTP_server&oldid=11361"
Personal tools