====== SOLoist Explorer ======
SOLoist Explorer™ is a simple tool that provides an HTTP interface for:
  * writing and executing OQL queries (results in HTML or Excel sheet; see generated SQL, etc.)
  * browsing the UML model
  * browsing the object space
It is implemented as a servlet in the SOLoist library.

===== Basic Installation =====
The servlet should be added to web.xml of your web application:
<file xml>
<servlet>
	<servlet-name>OQLServlet</servlet-name>
	<servlet-class>rs.sol.soloist.server.server.OQLServlet</servlet-class>
</servlet>

<servlet-mapping>
	<servlet-name>OQLServlet</servlet-name>
	<url-pattern>/oql</url-pattern>
</servlet-mapping>
</file>

The servlet will be accessible at the given URL, e.g. [[http://localhost:8080/MyWebApplication/oql]].

===== Advanced Installation =====

==== Authentication ====
OQLServlet provides no authentication mechanism whatsoever. You should use application specific filters (e.g. LoginFilter from EmptyProject).

==== Customization ====
OQLServlet supports the following init parameters:
  * title - Text to be used as the page title (default: SOLoist Explorer).
  * stylesheet - URL of the external CSS stylesheet to be used instead of the default style.
  * method - HTTP method used for HTML form submission. Values: GET (default) or POST.

Example:
<file xml>
<servlet>
	<servlet-name>OQLServlet</servlet-name>
	<servlet-class>rs.sol.soloist.server.server.OQLServlet</servlet-class>
	<init-param>
		<param-name>method</param-name>
		<param-value>GET</param-value>
	</init-param>
</servlet>
</file>

===== Troubleshooting =====

==== Problem with UTF-8 encoding when using GET method ====

There might be a problem if some servlet containers (e.g. Tomcat) do not use UTF-8 to parse request parameters from the query string of the request URI.
There are two soloutions to this problem:
  - solution(partial): Make OQLServlet use POST method instead.
  - solution (Tomcat only): Make Tomcat use UTF-8 encoding for request parameters encoded in query string. Edit server.xml and add useBodyEncodingForURI="true" to Connector, for example: <file xml><Connector connectionTimeout="20000" port="8080" protocol="HTTP/1.1" redirectPort="8443" useBodyEncodingForURI="true"/></file> Alternatively, you might use URIEncoding="UTF-8".
More info about configuring Apache Tomcat can be found on [[http://tomcat.apache.org/tomcat-7.0-doc/config/http.html|Apache Tomcat website]].