Download SIMOTION servlets

SIMOTION servlets
Programming Manual
11/2010
Introduction
1
Scope of functions
implemented
2
Scope of delivery
3
Installation
4
Implementing the servlet API
5
Creating user servlets
6
Configuration file
(JSERVER.XML)
7
Sample servlet and
configuration
8
Legal information
Warning notice system
This manual contains notices you have to observe in order to ensure your personal safety, as well as to prevent
damage to property. The notices referring to your personal safety are highlighted in the manual by a safety alert
symbol, notices referring only to property damage have no safety alert symbol. These notices shown below are
graded according to the degree of danger.
DANGER
indicates that death or severe personal injury will result if proper precautions are not taken.
WARNING
indicates that death or severe personal injury may result if proper precautions are not taken.
CAUTION
with a safety alert symbol, indicates that minor personal injury can result if proper precautions are not taken.
CAUTION
without a safety alert symbol, indicates that property damage can result if proper precautions are not taken.
NOTICE
indicates that an unintended result or situation can occur if the corresponding information is not taken into
account.
If more than one degree of danger is present, the warning notice representing the highest degree of danger will
be used. A notice warning of injury to persons with a safety alert symbol may also include a warning relating to
property damage.
Qualified Personnel
The product/system described in this documentation may be operated only by personnel qualified for the specific
task in accordance with the relevant documentation for the specific task, in particular its warning notices and
safety instructions. Qualified personnel are those who, based on their training and experience, are capable of
identifying risks and avoiding potential hazards when working with these products/systems.
Proper use of Siemens products
Note the following:
WARNING
Siemens products may only be used for the applications described in the catalog and in the relevant technical
documentation. If products and components from other manufacturers are used, these must be recommended
or approved by Siemens. Proper transport, storage, installation, assembly, commissioning, operation and
maintenance are required to ensure that the products operate safely and without any problems. The permissible
ambient conditions must be adhered to. The information in the relevant documentation must be observed.
Trademarks
All names identified by ® are registered trademarks of the Siemens AG. The remaining trademarks in this
publication may be trademarks whose use by third parties for their own purposes could violate the rights of the
owner.
Disclaimer of Liability
We have reviewed the contents of this publication to ensure consistency with the hardware and software
described. Since variance cannot be precluded entirely, we cannot guarantee full consistency. However, the
information in this publication is reviewed regularly and any necessary corrections are included in subsequent
editions.
Siemens AG
Industry Sector
Postfach 48 48
90026 NÜRNBERG
GERMANY
Copyright © Siemens AG 2010.
Technical data subject to change
Table of contents
1
Introduction................................................................................................................................................ 5
2
Scope of functions implemented................................................................................................................ 7
3
Scope of delivery ....................................................................................................................................... 9
4
Installation ............................................................................................................................................... 11
5
Implementing the servlet API ................................................................................................................... 13
6
Creating user servlets.............................................................................................................................. 17
7
Configuration file (JSERVER.XML).......................................................................................................... 19
8
Sample servlet and configuration............................................................................................................. 21
Index........................................................................................................................................................ 25
SIMOTION servlets
Programming Manual, 11/2010
3
Table of contents
SIMOTION servlets
4
Programming Manual, 11/2010
1
Introduction
SIMOTION servlets are the implementation of a servlet container.
Servlets are programs written in Java, which extend the capabilities of servers that
communicate via a request/response protocol. Theoretically, they are not bound to one
server protocol (HTTP), but are generally used in conjunction with HTTP/web servers.
The web container provides the runtime environment for web applications with their servlets
and can run on a different machine than the web server (load distribution,
safety/redundancy).
In a SIMOTION context, servlets run in SIMOTION - IT Virtual Machine (implementation of a
Java runtime environment) and are, therefore, afforded the option of using the SIMOTION
API (giving access to SIMOTION RT, NVRAM, and logging objects).
This document describes the scope of functions that are implemented, how the servlet
container is parameterized and started, and how a sample Java servlet is commissioned.
%URZVHU
UHVSRQVH
UHTXHVW
UHVSRQVH
:HEVHUYHU
:HEFRQWDLQHU
UHTXHVW
Figure 1-1
Servlet command sequence
SIMOTION servlets
Programming Manual, 11/2010
5
Introduction
SIMOTION servlets
6
Programming Manual, 11/2010
Scope of functions implemented
2
"Java™ Servlet Specification, V2.2" supports SIMOTION servlets;
however, not all of the concepts from the standard servlet API are implemented in
SIMOTION servlets.
The following are implemented:
● Differentiation between type of request (GET, POST)
● Access to all parameters of the request (from both the URL and form data)
● Access to the content of the request
● Access to the request header
● Specification of the response status
● Specification of the response header
● Writing of the response content
● Logging
● Initialization parameters from configuration file for servlets
● Servlet context with attribute management and initialization parameters
These enable the implementation of fully-fledged servlets, including structure and entry form
editing features (e.g. for Web browsers).
The section titled Implementing the servlet API (Page 13) contains a detailed description of
the functions implemented.
More advanced concepts such as the following are not implemented:
● Support for HTTP sessions
● Support for RequestDispatcher
● Support for security functionality
● Access to client information (remote host, etc.)
● Internationalization (only the ISO-8859-1 character set is available)
● Java server pages
Note
Security functionality
An authentication feature is implemented within the connection to the SIMOTION web
server, which enables you to limit access to servlets as standard in the interests of
security.
However, the Java security functions defined within the servlet API (such as the rolebased security concept) are not implemented.
SIMOTION servlets
Programming Manual, 11/2010
7
Scope of functions implemented
SIMOTION servlets
8
Programming Manual, 11/2010
3
Scope of delivery
The following files are integral parts of SIMOTION servlets:
File name
Description
svltapi.jar
Java library containing the standard servlet API.
svltimpl.jar
Java library containing the implementation of the servlet container.
simotion_servlets_doc.zip
Online documentation of the servlet API (HTML format).
simotion_servlets_demo.zip
Java source code for sample servlet.
JSERVER.XML
Sample servlet configuration file.
SIMOTION servlets
Programming Manual, 11/2010
9
Scope of delivery
SIMOTION servlets
10
Programming Manual, 11/2010
Installation
4
SIMOTION - IT Virtual Machine must be installed and configured SIMOTION servlets.
To operate SIMOTION servlets, Java libraries svltapi.jar and svltimpl.jar must be stored on
the target system.
As of SIMOTION V4.1 SP4, these Java libraries must be stored in the following directory:
● /SIEMENS/SIMOTION
The configuration files supplied assume that the SIMOTION Java system libraries are
located in this directory,
meaning that Java library svltapi.jar, which contains the standard servlet API, needs to be
incorporated into the JamaicaVM path.
The most straightforward way of doing this is to expand the setting for the
BOOTCLASSPATH accordingly in VMCONFIG.INI:
BOOTCLASSPATH= b:/siemens/simotion/simotion.jar;b:/siemens/simotion/svltapi.jar
Note
In SIMOTION - IT Virtual Machine, a semicolon must always be specified as a CLASSPATH
separator.
To start the servlet container automatically, you need to insert the following line in
JINVOKE.XML:
<AUTOSTART LIBRARY="B:/SIEMENS/SIMOTION/SVLTIMPL.JAR"
CLASSNAME="com.siemens.ad.SIMOTION.servlets.ServletContainer"/>
User servlets must be zipped into a Java library (JAR or ZIP file) and stored in the current
working directory of the target system.
To load a user servlet, all you need to do is enter the relevant information in configuration file
JSERVER.XML. This configuration file must also be stored in the current working directory of
the target system.
Note
The software/libraries are available on the U&A DVD at
\VOL2\AddOn\4_Accessories\Simotion_IT\5_Simotion_VM
SIMOTION servlets
Programming Manual, 11/2010
11
Installation
SIMOTION servlets
12
Programming Manual, 11/2010
Implementing the servlet API
5
"Java™ Servlet Specification, V2.2" supports SIMOTION servlets;
for the servlet API itself, the relevant implementation of the "Apache Jakarta Project" is used.
This has been developed by the Apache Software Foundation (http://www.apache.org/) and
does not offer support for Java server pages.
Essentially, this means that unless Java server pages need to be supported, all of the
specified interfaces and classes for the servlet API are available. Additionally, the online
documentation for the servlet API provides full descriptions of all the interfaces and classes it
contains.
Certain interfaces, as well as certain interface methods, are not supported in the first version
of SIMOTION servlets, as they are not required for simple servlets.
Generally speaking, methods referred to in the servlet specification as "deprecated"
(meaning that they are outdated and should no longer be used) are not supported.
If certain interface methods are not supported, calling them will trigger an exception of type
"UnsupportedOperationException".
The table below provides both a detailed list of what is included in the servlet API and a
description of the scope of functions implemented in SIMOTION servlets.
javax.servlet package
RequestDispatcher
Not implemented
ServletConfig
Fully implemented
ServletContext
The following methods are implemented:
public int getMajorVersion()
public int getMinorVersion()
public void log(String msg)
public void log(String msg, Throwable throwable)
public String getServerInfo()
public String getInitParameter(String name)
public Object getAttribute(String name)
public Enumeration getAttributeNames()
public void setAttribute(String name, Object object)
public void removeAttribute(String name)
public String getContextPath()
SIMOTION servlets
Programming Manual, 11/2010
13
Implementing the servlet API
ServletRequest
The following methods are implemented:
public int getContentLength()
public String getContentType()
public ServletInputStream getInputStream() throws IOException
public String getParameter(String name)
public Enumeration getParameterNames()
public String[] getParameterValues(String name)
public String getProtocol()
public String getServerName()
ServletResponse
The following methods are implemented:
public ServletOutputStream getOutputStream() throws IOException
public void setContentType(String type)
public void reset()
public boolean isCommitted()
public void flushBuffer() throws IOException
SingleThreadModel
Already implemented as appropriate in servlet API
GenericServlet
Already implemented as appropriate in servlet API
ServletInputStream
Fully implemented
ServletOutputStream
Fully implemented
ServletException
Already implemented as appropriate in servlet API
UnavailableException
Already implemented as appropriate in servlet API
javax.servlet.http package
HttpServletRequest
The following methods are implemented:
public Cookie[] getCookies()
public long getDateHeader(String name)
public String getHeader(String name)
public Enumeration getHeaderNames()
public int getIntHeader(String name)
public String getMethod()
public String getContextPath()
public String getPathInfo()
public String getQueryString()
public String getRequestURI()
public String getServletPath()
SIMOTION servlets
14
Programming Manual, 11/2010
Implementing the servlet API
HttpServletResponse
The following methods are implemented:
public void addCookie(Cookie cookie)
public boolean containsHeader(String name)
public void sendError( int sc, String msg ) throws IOException
public void sendError(int sc) throws IOException
public void setDateHeader(String name, long date)
public void setHeader(String name, String value)
public void setIntHeader(String name, int value)
public void setStatus(int sc)
HttpSession
Not implemented
HttpSessionBindingListener
Not implemented
HttpSessionContext
Not implemented
Cookie
Already implemented as appropriate in servlet API
HttpServlet
Already implemented as appropriate in servlet API
HttpSessionBindingEvent
Already implemented as appropriate in servlet API
HttpUtils
Already implemented as appropriate in servlet API
javax.servlet.jsp package
This package (along with its subpackages) is not included in SIMOTION servlets.
SIMOTION servlets
Programming Manual, 11/2010
15
Implementing the servlet API
SIMOTION servlets
16
Programming Manual, 11/2010
Creating user servlets
6
User servlets are created on a development computer.
A Java SDK (Java SE Development Kit) is required for compiling Java user programs. We
recommend "Java 2 Platform, V1.3.x" with the Java JDK (Java Development Kit) installed.
To enable the Java compiler to find the classes referenced within the servlet API, the
relevant Java library must be specified during compilation.
E.g.:
javac –classpath svltapi.jar ...
It is also necessary to specify the relevant Java library during compilation if classes are
referenced by the SIMOTION API as well.
E.g.:
javac –classpath svltapi.jar;simotion.jar ...
Comment:
The separator within the CLASSPATH specification is platform-specific. If a Windows
development computer is being used, a semicolon must be specified, while a colon must be
specified on a Unix development computer.
To ensure that the user servlet will not use any Java system classes that are not available
within the SIMOTION - IT Virtual Machine runtime environment, during compilation the Java
library can also be specified with the system classes as a reference.
E.g.:
javac –bootclasspath simotion_systemclasses.jar –classpath
svltapi.jar ...
Following compilation, all of the user program classes must be zipped into a Java library.
E.g.:
jar –cvf testsvlt.jar ...
Following this, the Java library can be transferred to the target system along with the user
servlet and loaded by the servlet container.
SIMOTION servlets
Programming Manual, 11/2010
17
Creating user servlets
SIMOTION servlets
18
Programming Manual, 11/2010
Configuration file (JSERVER.XML)
7
Configuration file JSERVER.XML contains the settings for the SIMOTION servlet container
and the servlets to be loaded.
XML notation must be used for the structure of the configuration file. A simple XML parser
(Nano/XML/Lite) is integrated in SIMOTION - IT Virtual Machine that is perfectly adequate
for editing the configuration file.
Before storing the configuration file on the target system, you are advised to display it in a
web browser, for instance, so that any syntax errors can be made immediately apparent (if
the configuration file has not been created using a special XML editor). NanoXML, in
particular, deals with error messages very economically.
The individual XML configuration file elements are described below:
ROOT element
SIMSERV must be used as the ROOT element:
<?xml version="1.0" standalone="yes"?>
<SIMSERV>
<!—Initialization parameter of context -->
<INITPARAM NAME="AParameter" VALUE="aValue"/>
<!-- SERVLET elements, for example, are listed here -->
</SIMSERV>
All other elements must then be specified within the ROOT element.
The example above contains just one initialization parameter, as described below.
INITPARAM element
The ROOT element can contain any number of INITPARAM elements. These initialization parameters can be queried from
servlets using the Servlet Context,
meaning that they are available for all servlets.
The following attributes are evaluated:
NAME
Name of the initialization parameter.
If this attribute is missing, the element will not be evaluated any further.
VALUE
Value of the initialization parameter.
If this attribute is missing, the empty string is used as the value.
SERVLET element
A SERVLET element contains information about the servlet to be loaded.
The name of the Java class that implements the servlet and the path (part of the URL following the ContextPath) under
which the servlet is to be registered must be specified for a servlet that is to be loaded.
You can specify several SERVLET elements, meaning that it is possible to load several servlets.
The following attributes are evaluated:
SIMOTION servlets
Programming Manual, 11/2010
19
Configuration file (JSERVER.XML)
LIBRARY
Name of the Java library (JAR or ZIP file) that contains the servlet.
The name specification can be either absolute or relative.
If the specification is relative, i.e. only the file name is specified without the path, the file itself
must be in the current working directory.
Specifying this is optional. If no Java library is specified, the Java class for the servlet must be
located in the CLASSPATH.
CLASSNAME
Name of the Java class for the servlet.
PATH
Path under which the servlet is to be registered within the ServletContext.
NAME
Name of the servlet.
Providing a name is optional and serves a purely informational purpose (the getServletName()
method returns the name).
If no specification is made, the name of the Java class is used as the servlet name.
INITPARAM element
A SERVLET element can contain any number of INITPARAM elements.
There initialization parameters can be queried within the servlet by means of the servlet
configuration, and apply to this servlet only.
In terms of structure, the INITPARAM element for servlets is identical to the one for the
ServletContext (see INITPARAM element).
Examples of SERVLET elements
In this example, two servlets are loaded.
Java class MyServlet is loaded from the MYSVLT.JAR Java archive and registered under
/myServlet within the ServletContext. The servlet can query the two initialization parameters. The
name of the servlet matches that of the Java class.
A client references the servlet via http://<host>/servlet/myServlet
The TestServlet Java class is loaded via the system class loader and registered under path /test
within the ServletContext (in this case, the TestServlet Java classes must be located in the
CLASSPATH of SIMOTION - IT Virtual Machine).
The servlet has no initialization parameters. The name of the servlet is "A test servlet".
A client references the servlet via http://<host>/servlet/test
<SERVLET LIBRARY="MYSVLT.JAR" CLASSNAME="MyServlet"
PATH="/myServlet">
<INITPARAM NAME="AParameter" VALUE="aValue"/>
<INITPARAM NAME="AnotherParameter" VALUE="anotherValue"/>
</SERVLET>
<SERVLET CLASSNAME="TestServlet" PATH="/test"
NAME="A test servlet"/>
SIMOTION servlets
20
Programming Manual, 11/2010
Sample servlet and configuration
8
A sample servlet in Java source code format is included in the scope of delivery as a basic
help method. Sample configuration JSERVER.XML may be used accordingly.
DemoServlet.java
The following section contains an example illustrating the basic principles of how a client
request is edited within a concrete servlet.
/*
* ==============================================================
* A simple servlet to demonstrate how to build a user-servlet.
*
* The servlet generates some "plain-text" only.
*
* Copyright (C) 2004 Siemens AG. All rights reserved.
* ==============================================================
*/
// Necessary servlet API
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
// Possible io exceptions
import java.io.IOException;
import java.io.PrintWriter;
SIMOTION servlets
Programming Manual, 11/2010
21
Sample servlet and configuration
/*
* A simple servlet, which generates only a textual response.
*/
public class DemoServlet extends HttpServlet
{
/*
* Generate response for a GET-Request.
*/
public void doGet( HttpServletRequest request,
HttpServletResponse response )
throws ServletException, IOException
{
// "request" could be used to query additional
// information
// e.g. parameters ...
// Set ContentType of the response
response.setContentType("text/plain");
// Obtain PrintWriter for writing response
PrintWriter out = response.getWriter();
// Write response
out.println("Hello SIMOTION Servlets!");
}
}
The sample servlet only generates simple text and does not require any parameters.
A servlet that wishes to have an entry form displayed in a browser generates the form in
HTML and writes it to the browser as a response to a GET request. In order to edit the entry
form, this type of servlet implements editing for the POST request as well, evaluates the form
parameters within this, and generates a relevant response again.
JSERVER.XML
The configuration file supplied shows how the sample servlet can be loaded and how a
DumpServlet contained in SIMOTION servlets can be activated. This is useful for the
purpose of viewing the current initialization parameters in the ServletContext.
SIMOTION servlets
22
Programming Manual, 11/2010
Sample servlet and configuration
<?xml version="1.0" standalone="yes"?>
<SIMSERV>
<!-- Example of a SIMOTION servlets configuration -->
<!-- ServletContext parameters -->
<INITPARAM NAME="ContextParam1" VALUE="ContextValue1"/>
<INITPARAM NAME="ContextParam2" VALUE="ContextValue2"/>
<!-The previously compiled demo servlet is loaded
and must be zipped into SVLTDEMO.JAR and stored
on the target system.
The demo servlet is registered for path
/demo, and can, therefore, by accessed by the client via
http://<host>/servlet/demo
-->
<SERVLET LIBRARY="SVLTDEMO.JAR" CLASSNAME="DemoServlet"
PATH="/demo" NAME="Demo-Servlet"/>
<!-No LIBRARY needs to be specified for the DumpServlet included as
standard.
By way of a response, the DumpServlet provides information about
the current request and initialization
parameters for the context and servlet (if specified),
and can be registered for simple checking of the context
initialization parameters,
for example.
The dump servlet is registered for path
/dump/*, for example, and can, therefore, be accessed by the
client via http://<host>/servlet/dump
or even http://<host>/servlet/dump/APathInfo
-->
<SERVLET CLASSNAME="com.siemens.ad.SIMOTION.servlets.DumpServlet"
PATH="/dump/*" NAME="Sample DumpServlet">
<INITPARAM NAME="ServletParam1" VALUE="ServletValue1"/>
<INITPARAM NAME="ServletParam2" VALUE="ServletValue2"/>
</SERVLET>
</SIMSERV>
SIMOTION servlets
Programming Manual, 11/2010
23
Sample servlet and configuration
SIMOTION servlets
24
Programming Manual, 11/2010
Index
C
Configuration file JSERVER.XML, 19
D
DemoServlet.java, 21
F
Functional scope, 13
I
Installation of SIMOTION - IT Virtual Machine, 11
J
JSERVER.XML, 19
JSERVER.XML example configuration, 21
L
Limiting access, 7
S
Scope of supply, 9
Servlet API, 13
SIMOTION servlets scope, 7
U
User servlets, 17
SIMOTION servlets
Programming Manual, 11/2010
25
Index
SIMOTION servlets
26
Programming Manual, 11/2010