JavaServer Pages Tag Library
This section describes the JavaServer PagesTM (JSP) tags available for creating dynamic web-based applications on top of Mulgara. The tag library includes general tags for communicating with a Mulgara server.
Software Requirements
The Mulgara custom tag libraries depend on a servlet container that supports the JavaServer Pages Specification, version 1.1 or higher. Some of the examples listed in this section make use of the Jakarta Taglib libraries.
Configuring your Web Application
Follow these steps to configure your web application to use the Mulgara tag libraries:
- Copy the tag library JAR files to the
/WEB-INF/lib subdirectory of your web application - Add a
<taglib> element to your web application deployment Descriptor in /WEB-INF/web.xml , as follows:<taglib> <taglib-uri>http://mulgara.org/mulgara/taglibs/tks</taglib-uri> <taglib-location>/WEB-INF/lib/tks-tag-2.1.jar</taglib-location> </taglib>
To use the general Mulgara tags from the library in your JSP pages, add the following directive at the top of each page:
<%@ taglib prefix="tks" uri="http://mulgara.org/mulgara/taglibs/tks"%>
Where tks is the tag name prefix you want to use for tags from the Mulgara library. You can change this to any prefix you like, but do not change the URL.
Note - All the examples in this section assume that the tag libraries are prefixed as shown above.
answer
Retrieves query answers from a statement.
|
|
|
|
|
|
Tag Body
|
JSP
|
Restrictions
|
None
|
Attributes
|
Name
|
Required
|
Runtime Expression Evaluation
|
Mulgara Version
|
|
id
|
false
|
true
|
n/a
|
|
If set, it saves the specified answer to a variable with this name into the page context. To save the variable to a different context, use the scope attribute.
|
|
statement
|
true
|
true
|
n/a
|
|
Specifies the id of the statement to retrieve answers from. If no statement with the id exists, an exception occurs.
|
|
query
|
true
|
true
|
n/a
|
|
The name of query to retrieve the answer of. The query with this id must be contained within the statement tag specified. Returns nothing if a query with that name does not exist.
Note - You must specify the name of the query in the execute tag for its result to be available in the answer tag. This is because by default, the statement tag sends queries in a single batch, and receives answers in a single batch.
|
|
scope
|
false
|
true
|
n/a
|
|
The scope of the variable created to hold the answer. Values must be one of page , request , session or application . If not defined, the variables are created in the page context.
|
Scripting Variables
|
Name
|
Type
|
|
|
[id]
|
org.w3c.dom.Document
|
|
|
If the id attribute is set on, the tag org.w3c.dom.Document containing the specified answer is set in the page context. You can override the scope of the variable created by setting the scope attribute.
|
Example
|
<%-- execute a statement (saving a list of answers to a variable named stmt2) --%> <tks:statement id="stmt2">
<%-- set the iTQL query --%> <tks:query> select $subj $obj from rmi://mysite.com/server1#dc where $subj rdfs:label $obj ; </tks:query>
<%-- set another iTQL query --%> <tks:query id="alltriples"> select $subj $obj $pred from rmi://mysite.com/server1#foo where $subj $pred $obj ; </tks:query>
<%-- execute the query --%> <tks:execute/>
<%-- execute the query --%> <tks:execute query="alltriples"/>
</tks:statement>
<%-- get the answer to a named query --%> <tks:answer statement="stmt2" query="alltriples"/>
<%-- save the answer to a named query in a request scoped variable named allTriplesAnswer --%> <tks:answer statement="stmt2" id="allTriplesAnswer" query="alltriples" scope="request"/>
<%-- the following will not return any results as the execute tag does not specify a query --%> <tks:statement id="answers2"> <tks:query id="query1"> select $title from rmi://mysite.com/server1#tmex where (http://mulgara.org/projects/mulgara/data/doc49.htm $y http://mulgara.org/mulgara/Document#Document ) and ( $node http://mulgara.org/mulgara/tool/HtmlExtractor#title $title ) ; </tks:query> <tks:execute/> </tks:statement>
<tks:answer statement="answers2" query="query1"/>
|
execute
Executes queries in a statement.
|
|
|
|
|
Tag Body
|
Empty
|
Restrictions
|
Must be enclosed in a statement tag
|
Attributes
|
Name
|
Required
|
Runtime Expression Evaluation
|
Mulgara Version
|
|
query
|
false
|
true
|
n/a
|
|
If set, it denotes the query to execute. The query with this id must be contained within the same enclosing statement tag as the execute tag specifying it. An exception occurs if no query exists with this id.
|
Example
|
<%-- set the iTQL query --%> <tks:query> select $subj $obj from rmi://mysite.com/server1#dc where $subj rdfs:label $obj ; </tks:query>
<%-- execute the query --%> <tks:execute/>
|
init
Initializes the Mulgara JSP tag environment, by setting the SOAP endpoint of the Mulgara server.
|
|
|
|
|
Tag Body
|
Empty
|
Restrictions
|
To be called before using any other Mulgara tag that communicates with a Mulgara server
|
Attributes
|
Name
|
Required
|
Runtime Expression Evaluation
|
Mulgara Version
|
|
server
|
true
|
true
|
n/a
|
|
The URL of the SOAP endpoint of the Mulgara server containing metadata you are interested in. For example, http://<hostname>:<port>/driver/query
The URL is stored in the page context (by default) and is accessible as a java.net.URL with the key tks.server.soapendpoint
|
|
scope
|
false
|
true
|
n/a
|
|
The scope of the variables created for server and model. Value must be one of page , request , session or application . If not defined, the variables are created in the page context
|
Example
|
<%-- initialise the environment --%> <tks:init server="http://localhost:8080/driver/query"/>
<%-- display the SOAP endpoint --%> TKS server SOAP endpoint = <%= pageContext.getAttribute("tks.server.soapendpoint") %>
<%-- initialise the environment storing variables in session scope --%> <tks:init server="http://localhost:8080/driver/query" scope="session"/>
<%-- display the TKS server model --%> TKS server = <%= pageContext.getAttribute("tks.server.soapendpoint", PageContext.SESSION_SCOPE) %>
|
query
Adds an iTQL query to a statement.
|
|
|
|
|
Tag Body
|
JSP
|
Restrictions
|
Must be enclosed in a statement tag and the body must contain a single iTQL query. Use multiple query tags to issue multiple queries in a single statement
|
Attributes
|
Name
|
Required
|
Runtime Expression Evaluation
|
Mulgara Version
|
|
id
|
false
|
true
|
n/a
|
|
If set, it can be referenced by an execute tag to execute this query individually
|
Example
|
<%-- set the iTQL query --%> <tks:query id="query1"> select $subj $obj from rmi://mysite.com/server1#dc where $subj rdfs:label $obj ; </tks:query>
<%-- execute the query --%> <tks:execute query="query1"/>
|
render
Renders an XML document using a supplied stylesheet.
|
|
|
|
|
Tag Body
|
JSP
|
Restrictions
|
Must contain a body to transform
|
Attributes
|
Name
|
Required
|
Runtime Expression Evaluation
|
Mulgara Version
|
|
stylesheet
|
true
|
true
|
n/a
|
|
The relative path to the XSL stylesheet to use to render the tag body contents
|
Example
|
<%-- render the results of a query --%> <tks:render stylesheet="/default.xsl">
<%-- execute a statement --%> <tks:statement>
<%-- set the iTQL query --%> <tks:query> select $subj $pred $obj from rmi://mysite.com/server1#foo where $subj $pred $obj ; </tks:query>
<%-- execute the query --%> <tks:execute/>
</tks:statement>
</tks:render>
|
statement
Sends queries to a Mulgara instance.
|
|
|
|
|
Tag Body
|
JSP
The body may contain multiple queries, which by default are sent to the Mulgara server (in the order that they appear) in one request, resulting in a single set of results (one SOAP message) being set to the output stream.
If you want to use multiple queries in a single statement tag, but do not want them to be sent in a batch, specify an id for each query tag, and use the execute tag with the query attribute set to the id of the query you wish to execute.
|
Restrictions
|
If called without the server or model attributes set, the init tag must precede the use of this tag.
The body must contain at least one query tag.
If you want to see results returned to the output stream, the body must also contain at least one execute tag. If not present, no results are returned to the output stream, or assigned to the variable specified with the id attribute.
|
Attributes
|
Name
|
Required
|
Runtime Expression Evaluation
|
Mulgara Version
|
|
id
|
false
|
true
|
n/a
|
|
If set, a java.util.List containing org.w3c.dom.Documents representing the answers to each execute tag in the statement is set in the page context. The tag does not output the contents of the SOAP responses to the output stream.
|
|
server
|
false
|
true
|
n/a
|
|
If set, overrides the URL of the SOAP endpoint of the Mulgara server set using the init tag.
Note - This does not update the value, rather it sets a new URL for the execution of this tag only.
|
Scripting Variables
|
Name
|
Type
|
|
|
|
[id]
|
java.util.List
|
|
|
|
If the id attribute is set on the tag, a java.util.List containing answers to each execute tag in the statement in the form of org.w3c.dom.Documents is set in the page context.
This list is ordered according to the ordering of the execute tags. So in the example below, the list contains two elements, accessible as follows:
// get the answer to both queries Document answer1 = (Document) stmt1.get(0);
// get the answer to the second query Document answer3 = (Document) stmt1.get(1);
The ordering is shown as an execute tag with no query attribute and executes all queries in the corresponding statement tag (two of them shown in the example below). The second execute tag only executes the second query (all triples). The statement tag does not remove duplicates from its list of answers.
Note - That setting the id attribute on a query that returns a large answer may impact performance as the SOAP answer is parsed into a document.
|
Example
|
<%-- execute a statement --%> <tks:statement>
<%-- set the iTQL query --%> <tks:query> select $subj $obj from rmi://mysite.com/server1#dc where $subj rdfs:label $obj ; </tks:query>
<%-- set another iTQL query --%> <tks:query id="alltriples"> select $subj $obj $pred from rmi://mysite.com/server1#foo where $subj $pred $obj ; </tks:query>
<%-- execute all queries --%> <tks:execute/>
<%-- execute the query --%> <tks:execute query="alltriples"/>
</tks:statement>
|
|
|
|
© 2001-2004 Tucana Technologies, Inc. Some rights reserved. © 2006 The Mulgara Project. Some rights reserved. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
|