Word_Instructor_Class_Template

greasyservantInternet and Web Development

Jul 30, 2012 (5 years and 2 months ago)

484 views


Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
1

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.

Unit 6.

The WebSphere V5 Web Container

What This Unit is About

WebSphere is used to support e
-
business, which implies that the majority of
clients will be using a web browser to access WebSphere for z/OS V5.1
applications. In this
u
nit
,

we will discuss how the HTT
P request from a web
client is routed to a servlet module in the WebSphere for z/OS V5.1
application server web container, and the configuration you must do to
achieve this. There are two routes for the incoming request to take
:

direct to
the application s
erver HTTP Internal Transport, or routed through an
intervening HTTP server
.


What You Should Be Able to Do

After completing this unit, you should be able to:



Describe the components needed to run a WebSphere V5 web
application



Configure the administration

objects that are needed to activate web client
access to a WebSphere application



Describe how the request URL is processed so that the required servlet
class file is loaded for a request



Define the configuration elements needed to support the IBM HTTP
se
rver plug
-
in for WebSphere V5

How You Will Check Your Progress

Accountability:



Machine exercises

References




WebSphere for z/OS Version 5 InfoCenter

-





All topics by feature
-
> Environment
-
> Web servers
-
>




Configuring Web server plug
-
ins

GA22
-
7
958

WebSphere V5.1: Servers and Environment
,

chapter 12

Student Notebook


6
-
2

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.


















Figure
6
-
1

Unit
Objectives

ESNEG1.0

Notes:

Up till now in the class, the internal transport ports used by the application server to

receive
HTTP and HTTPS requests have been taken for granted. In this unit
,

the students now learn
how to set up the web container in the J2EE server, which includes the transport ports as well
as other items. The students will be shown two different ways
to set up web access
:



Deploying the HTTP Transport Handler in the J2EE server CR to catch the browser
request and again route it to the waiting servlet in the web container.



Using the WebSphere for z/OS V5.1 plug
-
in the HTTP server to catch the browser req
uest
and route it to the servlet running in an application server.

You will:



S
et up web connections to the MyIVT servlet, and be able to try both connection methods,
and learn how to set up a web container on a J2EE application server which will support
execution of web applications in that server including the internal transport ports



Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
3

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.



Learn the methodology needed to install the WebSphere for z/OS V5.1 plug
-
in on the
HTTP server as a way of connecting e
-
business clients to WebSphere EJB applications



Lear
n how to relate entries in the deployment descriptors for web application components
to the support of those web applications in the web container.

There is no real hardcopy reference documentation on the contents in this topic. All the
information on ena
bling web access is in the WebSphere for z/OS Version 5 InfoCenter. Use
this to prepare for the topic
.

To access the info center
, p
oint your browser to
:


http://www.ibm.com/software/webservers/appserv/infocenter.html

On the next panel, select the option “5
.1.x” in category “WebSphere Application Server,
WebSphere Application Server Network Deployment, WebSphere Application Server Express,
and WebSphere Application Server for z/OS”
.

Search for string “Configuring Web server plug
-
ins”. You can use the Advance
d Search option
to search only in WebSphere for z/OS
.


Student Notebook


6
-
4

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.


















Figure
6
-
2

Client Access to EJBs

ESNEG1.0

Notes:

In order to access an EJB (J2EE application), you must have some code that represents a
client to that EJB. In lab 1 of this class, you ran a batch job BBOWIVT which tested the IVT
program. The job uses BPXBATCH to run an OMVS shell sessi
on, and that session runs the
java application client class using the java command from the shell. This client made a
connection to the EJB using the “RMI over IIOP” (RMI/IIOP) protocol (block #2 above). The
reason why the fat client was used to verify the

IVP was because it's relatively easy to install
and execute without having to worry about things like web access to the base application
server.

However, in the real world of the
I
nternet, real clients will probably be using browsers as their
interface to

your application. In this case, the incoming request would be in HTTP protocol as
represented with block #3. On the server, the initial target is a servlet executing in the web
container of the server. The servlet then acts as the client to the EJB. It co
llects and formats
the HTTP request parameters, and uses an RMI/IIOP request to connect to the EJB and
request an answer. When the answer is returned, the servlet typically applies the necessary
HTML formatting and then sends the answer in HTTP to the real

client.



Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
5

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.

In WebSphere for z/OS V5.1, the servlet client of the EJB will execute in the web container
associated with a WebSphere application server. This application server hosting the servlet
does not have to be on the same z/OS as the server hosting the
EJB, but let us take the
simplest case for now.

The focus of this topic is how you can connect an incoming request from the web with a target
servlet “client” program that will execute in the web container. In many cases, the real reason
for contacting the

servlet is that it is the first step to requesting a service from an EJB
application to which the servlet provides access

The terminology used to refer to a J2EE servlet component (and its other piece
-
parts) is a
“web application”, often abbreviated to
webapp
. Let's focus on what that is.



Student Notebook


6
-
6

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.


















Figure
6
-
3

What’s a “Web Application
”?

bpkb䜱.M

Notes:

A “web application” is comprised of one or more servlets, any other Java classes that act as
utility classes

in support of the servlets,
static files

such as HTML pages and GIF/JPG
images
, as well as
JSPs

(Java Server Pages) used to for
mat dynamic output. All of those
pieces are important to the operation of the total web application, and taken together they
make up the “web application.”

It's important to distinguish a “web application” from an Enterprise Java Bean (EJB). They are
diffe
rent things according to the J2EE specification. They are run from within different types of
“containers” in the WebSphere for z/OS application server.

Servlets executing as part of a web application can access EJBs, and behave like a
“surrogate” applicati
on client to an EJB. The servlet controls the HTTP session with the
browser, and controls the format of input parameters and the format of the output returned to
the browser of the real client. The EJB concentrates on the business logic of the application
and access to corporate resources and data
.


©
Copyright IBM Corporation 2005
IBM zSeries
4
HTML
files
GIF/JPG
Images
JSPs
Servlets
Other
Utility
Classes
Web Application
Enterprise
JavaBeans
What's a "Web Application"?

"Web Applications" consist of servlets AND other elements that c
omprise the solution.

Web Applications are not equivalent to EJBs; however, Web Applic
ations can access
EJBs and get information from them.


Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
7

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.


















Figure
6
-
4

Basics of Accessing

Web Applications

ESNEG1.0

Notes:

In order for a person sitting at a browser on the network to access a WebSphere web
application
,

you need three fundamental code components
.

You need to have something act as an “HTTP Protocol Catcher”
.

The protocol used
coming
out of a browser is HTTP mapped on top of TCP/IP. A protocol catcher
--

such as the IBM
HTTP server
--

communicates with browsers using the HTTP protocol, and is capable of doing
the initial interpretation of what the request is all about.

You need
to have some process that is capable of recognizing that a request is for the
execution of a web application (servlet), and be able to
route the request to the correct
application server
-

one that hosts the correct web application.

Finally, you need to ha
ve an environment in which the servlet runs (the WebSphere web
container provides that). Also, that environment needs to be able to interpret the inbound
request, find the necessary
web application,
and then locate and execute the
appropriate
servlet

class

file.

Now let's explore this scenario in greater depth.


Student Notebook


6
-
8

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.


















Figure
6
-
5

HTTP P
rotocol Catchers in z/OS

ESNEG1.0

Notes:

In general, an “HTTP Protocol Catcher” is any program which communicates on the TCP/IP
network using requests formatted in HTTP protocol. A protocol catcher understands the HTTP
protocol and is capable of interpret
ing from the request format what the target of the request
is. When WebSphere for z/OS is active on the same system, a protocol catcher can be used
to route appropriate requests to WebSphere for z/OS web applications for processing.

In WebSphere for z/OS V
5.1, the primary protocol catcher is known as the
HTTP Internal
Transport
. This WebSphere component is configured to run in the CR address space of a
J2EE application server. The Internal Transport component will listen for incoming protocol
requests using

selected ports on the TCP/IP stack. When a request is received, the Internal
Transport validates that the request can execute in this server. Provided the request is valid,
the Internal Transport routes the request for execution to the web container in th
is server.

The other supported HTTP protocol catcher on z/OS is the
IBM HTTP server.

The HTTP
server listens for incoming HTTP requests from remote clients on the network. You can
activate the
WebSphere HTTP Plug
-
in

component in the HTTP server address spa
ce. The
plug
-
in can be configured to filter HTTP requests received by the HTTP server and direct


Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
9

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.

requests to run WebSphere web applications to the Internal Transport function of the
appropriate J2EE application server
.

The plug
-
in uses HTTP protocol to re
-
direct the Web request to the WebSphere for z/OS
Internal Transport. The J2EE Internal Transport validates the incoming request and then
schedules the request to run in the
web container

of the application server.

It is worth stressing here that once the
request has reached the web container, the web
application is scheduled in the same way, irrespective of the way in which the request was
“caught”. So the web application does not need to be aware of the route by which the request
arrived, although it can
find this out if it is important
.


Student Notebook


6
-
10

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.



















Figure
6
-
6

Overview of HTTP Internal Tr
ansport

ESNEG1.0

Notes:

The HTTP Internal Transport is a component that executes in the
CR

address space of a
J2EE application server. The Internal Transport will bind to two selected TCP/IP port
addresses, which are configured by the WebSphere for z/OS V
5.1 administrator, and listen for
incoming requests.

When an HTTP request is received, the Internal Transport checks the URL of the web
container definition in the application server configuration to see if it matches a web
application supported by this J
2EE server. If this request is supported, the HTTP handler
schedules the associated web application in the web container; if not, the request is failed.

The HTTP Internal Transport is configured in the J2EE server definition by using the
administration too
l. How to do this is described in
WebSphere V5.1: Servers and Environment
.

There is no FRCA support for web components retrieved in this way, but there is an alternative
called the Edge Side Include (ESI) cache. We will look at this later.



Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
11

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.



















Figure
6
-
7

WebSphere V5 Web Containers

ESNEG1.0

Notes:

Containers

are software constructs

within the J2EE Server Instances that are used as an
execution environment in which you run certain kinds of things. There are two kinds of
containers:



EJB containers
,

which run, naturally, EJBs



Web containers
,

which run web applications

Both container ty
pes provide services to the software elements that run within them. These
services are things such as security and naming services; things which the application
developer would have to code into their applications if they didn't exist as a standard part of

the container.

Web containers are designed to support the execution of servlets and JSPs, as well as the
serving out of static content such as HTML and JPG/GIF. They provide the J2EE runtime
platform for executing web applications. The configuration infor
mation for the web container is
part of the application server configuration.


Student Notebook


6
-
12

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.



















Figure
6
-
8

Configuration Options of the Web Container

ESNEG1.0

Notes:

The web container configuration object has the following configuration options

General Section



A pointer to the
default virtual host
,
used for management



A switch to enable
servlet
caching
. It can be used to improve the performance of servlet
and JSP files by serving requests from an in
-
memory cache managed by Dynamic
Caching. Cache entries contain the servlet's output, results of the servlet's execution, and
metadata. At application

assembly time, a developer needs to configure servlet cache
environment in a web application
-

caching is not automatically used for any servlet loaded

Thread Pool

-

Controls the execution threads used to dispatch servlets



Minimum and maximum number

of th
reads allowed in the pool



A
thread time
-
out

value
-

the number of milliseconds of inactivity that should elapse
before a thread is assumed dead and reclaimed.

©
Copyright IBM Corporation 2005
IBM zSeries
9
Configuration Options of the Web Container

General section

Default virtual host

Enable servlet caching

Thread pool

Pool minimum/maximum sizes

Thread inactivity timeout

Session management

Type of tracking
-
SSL ID tracking, cookies, URL rewriting

Session timeout

Security integration and session serialization

Session persistence

HTTP transports

Internal transport host name and port addresses


Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
13

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.

Session Management

A session is a series of requests to a servlet, originating from the same u
ser at the same
b
rowser. Sessions allow applications running in a Web container to keep track of individual
users and propagate data from one session request to the next. Typical use is a shopping cart
used when doing online shopping. A servlet distinguish
es (tracks) user requests by their
unique session IDs which must arrive with each request

Primary session data is kept in application server memory. By default, session memory is
not

made persistent
-

if the server fails, the session data is lost. You have

the option to make
session data persistent in a DB2 database (known as database persistent sessions) or using
memory replication. In
-
memory session data cannot be shared by multiple application servers

Session
c
onfiguration options include
:



Types of sess
ion tracking



Cookies

-

If user's browser is cookie
-
enabled, the session ID
is
stored as a cookie



URL rewriting
-

session ID is appended to the URL of the servlet or JSP file from which
the user is making requests



For HTTPS or SSL requests store
session id

in SSL information




Session time
-
out
-

how long a session can go unused before it is no longer valid



Security integration
-

if enabled, the Session Management facility associates the identity of
users with their HTTP sessions



Session persistence mechanism



Maximum in
-
memory session count


Student Notebook


6
-
14

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.



















Figure
6
-
9

Server Web Application Conf
iguration

ESNEG1.0

Notes:

This visual summarizes the configuration objects that are used to schedule and execute a web
application
:




Virtual Host

(object): A virtual host is a logical construct which can be used to make a
single host system appear to be m
ultiple logical hosts. This is used to distribute incoming
web requests to selected application servers.



Application Server

(object)
:
This contains the definition of the web container. The
definition identifies the ports used by the internal transport, the

characteristics of any HTTP
sessions, session time
-
out values, and much more. The application server object also
points to all applications installed in it.



Application

(object)
:

An application can include several web applications. Each web
application is

packaged in a *.war file. Each *.war file is also associated with a context root
-

a string which maps the URL of a request to the web application in that war file.



Finally, the web application *.war file can hold many servlet objects. The
web applicati
on
module

(object) holds metadata that can identify which servlet should be executed for a
request by the name of the servlet class file.

©
Copyright IBM Corporation 2005
IBM zSeries
10
Application
Server
J2EE
Application
Web App
Modules
Virtual
Hosts
Server Web Application Configuration

Virtual Host

a configuration object enabling a single host
machine to resemble multiple host machines

Is associated with one or more host aliases

<
host_name
/IP address><port number>

Application Server

Defines the web container where servlets execute

Defines HTTP "end points" (ports) for server HTTP
Internal Transport

Application

Has an index of all *.war files in the application

Information for each war file,

Virtual host map

Context root

Web App Module (= a war file)

Define Servlet names

Defines Servlet mappings

Names the Servlet class file


Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
15

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.



















Figure
6
-
10

Hosting Multiple Domain Names

ESNEG1.0

Notes:

Imagine you wish to host different web applications on the same system, and you want each
application to have a different URL. For ex
ample, imagine you wanted to set up a web site for
the police, the fire, and the tax authorities for the state of Maryland and the URLs have the
form shown at the top of the visual.

Now imagine you've set up your Domain Name Server so that the three differ
ent host names
all point to the same IP address, which is the adapter of your z/Series box. Those three
people, when they enter those different URLs, will all end up at the same adapter and the
same web server.

Assume that httpd.conf has Service statements

that pass the URLs to the plug
-
in, and the
plug
-
in has routed the requests to the WebSphere for z/OS web container. How might you
keep the applications of the three different agencies logically separate from one another?

To start with, you must understand

that the IP host name that the user sent in with his request
is passed along to the WebSphere for z/OS web container. The WebSphere for z/OS web

Student Notebook


6
-
16

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.

container has a mechanism known as “virtual hosts” that allows it to match the host domain
names received fro
m the browser with definitions in the webcontainer.conf so that requests
with taxes.state.md.us for example, can only see and execute those applications associated
with that host domain name. For this to be possible, the web container has to “bind” the
app
lications deployed into the server with the virtual hosts defined in the webcontainer.conf
file. This is done with something called “
context roots
.” Let's explore that next.



Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
17

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.



















Figure
6
-
11

Connecting Applications to Virtual Hosts

ESNEG1.0

Notes:

Before you can execute a J2EE web application in an application server, the deployer
uses
WSAD or the Assembly Toolkit to deploy the *.war file into an EAR file. Also during
deployment, they will define a “
context root
” related to the web application (*.war). The
deployment process stores a file named
application.xml

-

the “deployment desc
riptor”
-

in the
EAR file. The deployment descriptor defines all web applications in the ear file by name. For
each application, the <web>/</web> tags define the web application war file name and the
associated context root.

Before we talk about defining v
irtual hosts, let’s look at the logical structure of a virtual host
.



Name

-

define any name you like for the virtual host



A list of one or more
host aliases
, where each alias consists of
:



Host Name

-

Specifies IP address, DNS host name with domain name suf
fix, or just the
DNS host name. A wildcard of “*” matches any host name



Port
-

The port configured for server internal transport or IBM HTTP server

©
Copyright IBM Corporation 2005
IBM zSeries
12
application.xml
<!DOCTYPE application PUBLIC "
-
//Sun Microsystems,..
<application id="AutoPolicy">
<display
-
name>AutoPolicy</display
-
name>
<module id="AutoPolicy WebApp >
<web>
<web
-
uri>AutoTax.war</web
-
uri>
<context
-
root>/auto</context
-
root>
</web>
</module>
AAT
Context Root:
/auto
*.ear
file
Virtual Host: fire
Host Alias: fire.state.md.us:8020
Virtual Host: taxes
Host Alias: taxes.state.md.us:8020
Virtual Host: police
Host Alias: police.state.md.us:8020
Application: AutoPolicy
Web App:
AutoPolicy WebApp
Context Root = /auto
Virtual host mapping: taxes
1
Define virtual hosts
2
Install application in AppServer1
Map to
virtual
hosts
2
Server: AppServer1
Web Container
Default virtual host: default_host
3
Connecting Applications to Virtual Hosts

Student Notebook


6
-
18

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.

Table of supported mime types for requests

When you install an application into a WebSphere for z/OS applic
ation server, you must
associate each war file in the application with a virtual host. This is how it is done

To define virtual hosts, start the administration tool and then select Environment
-
>
Virtual
hosts
. The next panel will list virtual hosts curren
tly defined to WebSphere for z/OS V5.1.

Select the New button to create a new virtual host and then fill in the appropriate settings. In
the above example, the administrator has added 3 extra virtual hosts
-

one to correspond to
each of the authorities
.


N
ext, you install the application into your chosen application server (AppServer1 in our
example. As part of application installation, you are required to map each web application in
the application to at least one defined virtual host (you can do multiple
mappings). In our
example, the web application is mapped to virtual host taxes. The application configuration
object also contains the context root
-

more about that on the next page.

The definition of the web container inside an application server has a s
etting “Default virtual
host” which must point to a defined virtual host.



Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
19

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.



















Figure
6
-
12

How the Web Container Accepts a Request

ESNEG1.0

Notes:

It is t
ime to put the pieces together and have a look at how an incoming request to execute a
servlet is accepted by the web container.

When the application server is started up, the ser
ver reads the “HTTP Transports” information
from the web container configuration and makes the HTTP internal transport bind to the local
IP host name and the two ports specified. If host name is specified as an IP address or as a
genuine IP host name, the
internal transport binds to the IP stack related with that IP address
or host name. If the host name is “*”, the bind is done to all active IP stacks.

Let’s assume that a browser request comes in to port 8020. The URL is

http://taxes.state.md.us:8020/auto/
tax_filing

The web container removes the host name and port number from the incoming URL, leaving a
string called the URI. For our example
:

©
Copyright IBM Corporation 2005
IBM zSeries
13
HTTP
Internal
Transport
P 8020
CR
P 8021
HTTP
HTTPS
Virtual Host: taxes
Host Alias: taxes.state.md.us:8020
Application: AutoPolicy
Web App:
AutoPolicy WebApp
Context Root = /auto
Virtual host mapping: taxes
http:// taxes.state.md.us:8020 /auto /tax_filing
HTTP Transports
Host Port SSL
* 8020 false
* 8021 true
Web Container
app server initialization
Does
virtual host
match?
Application
present?
Fail request
Fail request
read request
Y
Y
N
N
Accept request
1
2
2
1
How the Web Container Accepts a Request

Student Notebook


6
-
20

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.

/auto/tax_filing

Now the container searches through the
J2EE applications

that are installed in the
application serv
er. For each J2EE application, the container locates all the
web applications

packaged in that J2EEapplication. The container takes the context root string for each web
application, and compares it character by character to the request URI, starting at the

beginning of the URI. If there is a match for all characters in the context root (the URI is
usually longer than the context root), the container decides that the request wants to run the
web application associated with the context root.

If no match is fo
und with any web application context root, the request fails
.

The target web application object will be associated with at least one virtual host. In our
example, the virtual host is called

taxes
. The web container now reads the list of aliases
associated
with virtual host taxes
-

there is only one alias entry
:

taxes.state.md.us:8020

This alias entry is now compared, using a
string compare
, with the host name and port (if
present) on the request URL. If there is an
exact
match, then the URL is authorized to

use this
virtual host, and therefore authorized to run the requested web application. Note
-

the case of
the URL does not have to match. For example
this

request URL still matches the alias entry
:

Taxes.STATE.md.us:8020

A virtual host alias entry can also

use the “*” as a wild card for the host name which signifies
any host name is acceptable. For example the alias “*:8020” would match the request URL as
well.

If the virtual host check is successful, the request is accepted for execution and the container
looks for the servlet it must execute. If check fails, so does the request.

What would happen to the following request URLs
-

assume that the IP address of host
taxes.state.md.us

is
59.1.1.8?

http://fire.state.md.us:8020/auto/tax_filing

http://59.1.1.8:802
0/auto/tax_filing

http://taxes.state.md.us:8020/automatic/tax_filing

Details


For the examples

http://fire.state.md.us:8020/auto/tax_filing

The request matches with the web application context root. The virtual host test fails because
the virtual host ali
as string is different
:

http://59.1.1.8:8020/auto/tax_filing


Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
21

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.

The request matches with the web application context root. The virtual host test fails because
the virtual host alias contains a host name. Although the IP address relates to the correct host
nam
e, this translation is not done during matching
:

http://taxes.state.md.us:8020/automatic/tax_filing

This
w
ill match both context root and virtual host. The request is accepted, but will fail when
trying to find the servlet
-

more on that in the next visual
s
.



Student Notebook


6
-
22

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.



















Figure
6
-
13

The Base Server Default Definitions

ESNEG1.0

Notes:

When

you first install the base application server, the installation process will define a single
virtual host named default_host. The host will have
five

aliases
:

* : <base server internal transport port number for HTTP>

* : <base server internal transport p
ort number for HTTPS>

<hostname> : <base server internal transport port number for HTTP>

<hostname> : <base server internal transport port number for HTTPS>

* : 80

The default_host virtual host is probably sufficient for testing on the base application se
rver.
The host alias “*: 80” is there in case you use the HTTP server plug
-
in and it assumes that the
HTTP server is listening on port 80
.


If you install the sample applications from WebSphere for z/OS V5.1 into the base application
server, you will invo
ke a web application from your browser to start each sample application.
The visual shows the context roots for each application. You use the following URL to start any
©
Copyright IBM Corporation 2005
IBM zSeries
14
These are HTTP Internal
Transport ports for base
application server
Virtual Host:
default_host
Host Alias: * : 9080
Host Alias: * : 9443
Host Alias: * : 80
Host Alias
<hostname>
:9080
Host Alias
<hostname>
:9443
Sample Applications

PlantsByWebSphere
ƒ
Context root:
/PlantsByWebSphere

SamplesGallery
ƒ
Context root:
/WSsamples

TechnologySamples
ƒ
Context root:
/TechnologySamples/
xxx
(where
xxx
identifies the sample app)

adminconsole
ƒ
Context root:
/admin

ivtApp
ƒ
Context root:
/ivt

petstore
ƒ
Context root:
/petstore
http://10.31.227.198:9080/PlantsByWebSphere
http://10.31.227.198:9080/PlantsByWebSphere/servlet/ShoppingServ
let
http://mvsw21.ilsvpn.ibm.com:9080/PlantsByWebSphere/servlet/Shop
pingServlet
Example of
some URLs that
will work
The Base Server Default Definitions


Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
23

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.

sample application. All the sample web applications are initially connected to virtual
host
default_host
.

To start any sample application, code the URL like this
:

http://
<host name or IP address>
:9080
<sample app context root>


Student Notebook


6
-
24

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.



















Figure
6
-
14

Web Applications Packaged in WAR Files

ESNEG1.0

Notes:

Up to this point we've just assumed that the web application is somehow available to the web
container for execution. Now
we'll focus on how a web application is packaged and deployed
into the web container.

All web applications deployed to a J2EE server web container must be in the form of a “WAR”
file.

WAR files are zip
-
format files much like JAR files. The WAR file contain
s the static content
such as the HTML and JPG/GIF files, as well as the JSP pages and the servlet class files. The
WAR file also includes an XML file that is the “deployment descriptor” for the web application.
The name of that file, zipped inside the WAR
file, is web.xml and it will always be in the /WEB
-
INF directory. As part of the packaging process where the WAR file is built, you (the packager)
provide information that is then put into the web.xml file. We'll show you what this web.xml file
looks like
on the next chart.

©
Copyright IBM Corporation 2005
IBM zSeries
15
Web Application

"WAR" stands for Web ARchive

A "zip format" file, much like a JAR

Has both files and sub
-
directories

WAR created by tools such as WebSphere
Studio

The "deployment descriptor" web.xml tells
the WebSphere web container about this
web application
/(base or root)
HTML, GIF/JPG and JSP files
/META
-
INF
MANIFEST.MF
/theme
Master.css
/WEB
-
INF
web.xml
/classes
/lib
Servlet.class
Output.jsp
Input.html
Logo.jpg
war
file
Server Instance
war
file
Web Container
Container Services for
Servlets/JSPs
Web
Applications
Packaged in WAR Files


Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
25

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.

During the deployment process, this WAR file is transferred to the z/Series server and placed
in the HFS directory structure for the application server configuration.

The key messages here are:



Web applications are packaged in WAR files
.



WAR files are like JAR files in that they're in a zip format (and can be unzipped using
WinZ
ip
)
.



A file called
web.xml

serves as the “deployment descriptor” for the web application
contained within the WAR file
.

Let's take a look at what that web.xml file

looks like...


Student Notebook


6
-
26

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.



















Figure
6
-
15

The web.xml “Deployment Descriptor”

bpkb䜱.M

Notes:

The web.xml file contains information the web container requires to resolve a request down to
a specific servlet to be run. This file is stored in the HFS on the z/Series machine in ASCII, so
if you try to browse it on the server it'll look garbled.

This is what the file looks like if you
download the file to your PC as a binary file and edit it.



The
<servlet> .. </servlet>

tags define a servlet in the web application. The <servlet
-
name> tag inside this definition identifies the
name

of the servlet
.




The
<servlet
-
class>

tag identifies the
servlet code

(class file). When this servlet is called,
the web container will go execute the code specified here.



The
<servlet
-
mapping>

provides the string used to
resolve a request

down to being
applicable to this
web application.

Let’s take a look at how this data can be used by the web container to find a servlet. Assume
this request URL coming in from the browser
:


http://10.31.22
7.198:9080/PlantsByWebSphere/servlet/ShoppingServlet

©
Copyright IBM Corporation 2005
IBM zSeries
16
<?xml version="1.0" encoding="UTF
-
8"?>
<!DOCTYPE web
-
app PUBLIC "
-
//Sun Microsystems, Inc.//DTD Web Application
<web
-
app id="WebApp_1">
<display
-
name>
PlantsByWebSphere Web Application
</display
-
name>
.......
<servlet id="Servlet_2">
<servlet
-
name>
ShoppingServlet
</servlet
-
name>
<description>Shopping Servlet</description>
<servlet
-
class>com.ibm.websphere.samples.plantsbywebspherewar.
ShoppingServlet</servlet
-
class>
</servlet>
........
<servlet
-
mapping id="ServletMapping_2">
<servlet
-
name>ShoppingServlet</servlet
-
name>
<url
-
pattern>
/servlet/ShoppingServlet
</url
-
pattern>
</servlet
-
mapping>
........
</web
-
app>
This file is read at
server startup time
when the web
application is started
and the war module is
loaded
Web Module
PlantsByWebSphere.war
-
web.xml
1
2
3
http:// 10.31.227.198:9080 /PlantsByWebSphere /servlet/ShoppingS
ervlet
CONTEXT ROOT
VIRTUAL HOST MAPPING
SERVLET MAPPING STRING
The web.xml "Deployment Descriptor"


Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
27

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.

Assume also that the context root for the web application
PlantsByWebSphere.war

shown
above is
/PlantsByWebSphere

First the web container checks that the URL matches the virtual host for the web applica
tion,
and if it matches, the host name and port are removed to leave the URI
:

/PlantsByWebSphere/servlet/ShoppingServlet

Then
,

the web container removes the context
-
root string from the URI, leaving the last part of
the URI. This remaining part is called t
he
servlet mapping string
.

/servlet/ShoppingServlet

The servlet mapping ids for all servlets defined in the web.xml file for application
PlantsByWebSphere.war
are now searched. The web container tests to see if the URL
pattern defined in a servlet mapping
id matches the servlet mapping string of the request. It
gets a hit on entry
ServletMapping_2.

The <servlet
-
name> tag in that entry contains the
name of the servlet related to this mapping id
-

it is
ShoppingServlet
. Note that it is the
application develo
per that decides what the servlet mapping id will be.

Finally, the web container searches all the
<servlet> .. </servlet>

entries in web.xml,
looking for an entry that has a <servlet
-
name> entry of .
ShoppingServlet.
It gets a hit on entry
servlet id="Serv
let_2". The <servlet class> tag in the <servlet> entry gives the name of the
servlet class file (the actual program) which must be executed for this request. It is
com.ibm.websphere.samples.plantsbywebspherewar
.


The web container then gets an available t
hread from the servlet thread pool and dispatches
this servlet class to execute in the servant region. If this is the first time the servlet has been
used, the class file will be compiled using the JIT before it is dispatched
.


Student Notebook


6
-
28

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.



















Figure
6
-
16

Putting It All Together

ESNEG1.0

Notes:

Now
we

put all the bits together in one picture.
As an example, we can take request URL
:

http://10.31.227.198:9080/PlantsByWebSphere/servlet/ShoppingServlet

When the URL arrives in the transport handler for an application server, the web container
starts off by extracting the request URI
,

which is
:

/Plan
tsByWebSphere/servlet/ShoppingServlet

It then scans the list of applications installed in the server, looking for web applications
installed in those applications. For each web application, it attempts to match the context root
of that web application with

the URI
.

The web container gets a successful match for the context root of web application
PlantsByWebSphere WebApp

in application
PlantsByWebSphere
.

©
Copyright IBM Corporation 2005
IBM zSeries
17
application
PlantsBy
WebSphere
server
BaseServer
web module
PlantsBy
WebSphere.war
Application: PlantsByWebSphere
Web App name: PlantsByWebSphere WebApp
Web App module: PlantsByWebSphere.war
Virtual host:
default_host
Context root: /PlantsByWebSphere
Web Module: PlantsByWebSphere.war
Servlet Mappings:
Servlet name: ShoppingServlet
Url pattern: /servlet/ShoppingServlet
Servlet Servlet name: ShoppingServlet
Class: com.ibm.websphere.samples.
Plantsbywebspherewar.ShoppingServlet
Virtual Host: default_host
Host Alias: * : 9080
Host Alias: * : 9443
Server: BaseServer
Transport Handler:
end points = 9080, 9443 (SSL)
Appl: PlantsByWebSphere
http:// 10.31.227.198:9080 /PlantsByWebSphere /servlet/ShoppingS
ervlet
CONTEXT ROOT
VIRTUAL HOST MAPPING
SERVLET MAPPING STRING
5
6
1
2
3
4
Putting It All Together


Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
29

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.

Web application
PlantsByWebSphere WebApp
has been connected to virtual host
default_host
. The request U
RL is checked against the aliases defined in the virtual host to
see if web container will accept the request. There is a successful match on alias “*:9080” and
the request is accepted.

The web application
PlantsByWebSphere WebApp
is associated with a web
module
PlantsByWebSphere.war
. The web container searches for the configuration object for this
web module

The web container removes the context root from the beginning of the request URI and the
remaining characters are called the servlet mapping string
.

/
servlet/ShoppingServlet

Then the web container searches all the servlet mappings in the web module web.xml file,
looking for a mapping entry which contains a
URL pattern

that matches the servlet mapping
string. It gets a hit with servlet mapping for servle
t name
ShoppingServlet
.

The last step is to get the name of the servlet class file. The web container searches the same
web.xml file, looking for a
Servlet
entry for servlet ShoppingServlet. When it finds the Servlet
entry, the Class setting names the clas
s of the servlet
-

it is
:

com.ibm.websphere.samples.plantsbywebspherewar.ShoppingServlet

The web container then dispatches the servlet class file under a thread in the SR address
space.

As you can see, there
are

a number of connections to be made and many
places where things
might go wrong. Also, in this discussion on dispatching servlets, we have not talked about
other activities performed by the web container such as client authentication, checking client
authorization to run this servlet, session managem
ent, and transaction handling. The security
issues are covered in Unit 7, but the others are beyond the scope of this class.

A final test
-

what would happen if the request URL was entered as

the following?


http://10.31.227.198:9080/PlantsByWebSphere
x
/ser
vlet/ShoppingServlet

Details


Looking at the test URL at the bottom
:



The context root for web application will still match OK



The virtual host check will be successful

when the web container generates the servlet mapping string by removing the context ro
ot
it will get the result
x/servlet/ShoppingServlet
. This string will not successfully match any
of the servlet mappings in the web application web.xml file and the request will fail as no
servlet can be found. You must be careful with context roots.


Student Notebook


6
-
30

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.



















Figure
6
-
17

How Web Apps Are Stored in the HFS

ESNEG1.0

Notes:

Once the admin
istration tool has done
its

thing during the deployment process, the WAR file
that was inside the EAR file will be exploded into a real HFS directory structure. By default, the
web application directory structure will be located under the directory
:


/ILS/
WAS500/baseconfig/AppServer/installedApps/
<cellname>
/
<webapp_ear_name>

although you can change this location when you install the application.

From there, a directory with the same name as the WAR file is created. That's right... a
directory. Under that d
irectory you will find files and further directories, all taking a format
pretty much equal to that contained in your original WAR file (Check it out sometime: use
WinZ
ip

to view the contents of a WAR file, then deploy it to the WebSphere for z/OS Runtime
and take a look at the resulting HFS directory structure).

©
Copyright IBM Corporation 2005
IBM zSeries
18
ƒ
All files either
BINARY or ASCII ...
no EBCDIC!
ƒ
WAR file expanded
during deployment
similar to structure in
the original WAR file
/PlantsByWebSphere.war
Cell Name
Application Name
Initial WAR file name, now
used as a directory name
Deep directory structure that
contains the actual servlet
class file. This represents a
Java "package"
Static Files
(html, jsp, css)
account.jsp
applycss.js
banner.html
login.jsp
......
/Images
add_to_cart.jpg
button_change.gif
......
/META
-
INF
MANIFEST.MF
/WEB
-
INF
/classes
/com
/...
web.xml
ibm
-
web
-
bnd.xmi
ibm
-
web
-
ext.xmi
/Base_CB
/ILS/WAS510/APPCNFG/AppServer/installedApps
/PlantsByWebSphere.ear
Deployment
Descriptor
Static images
(gif, jpg)
How Web Apps Are Stored in the HFS


Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
31

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.

The key things here are the following:



The
static files
, such as HTML files, JSP pages, and style sheets (*.css) are in the “root”
or base of the directory.



Any
images

are stored in the
/Images

su
bdirectory
.



The
/WEB
-
INF

directory contains the web.xml file, the IBM extended descriptors, as well as
the package (in the form of a further set of sub
-
directories) of the actual servlet code
-

these will be class files.



Files are stored in BINARY or ASCII

format, and never in EBCDIC. Therefore, using the
browsing functions of ISPF won't work.

This is what it looks like post
-
deployment.


Student Notebook


6
-
3
2

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.



















Figure
6
-
18

WebSphere V5 Plug
-
in for z/OS HTTP Server

ESNEG1.0

Notes:

Web server plug
-
ins enable the Web server to communicate requests for dynamic content,
such as servlets, to the application
server. The WebSphere HTTP Plug
-
in for z/OS ships as
part of the WebSphere Application Server for z/OS product. To use this plug
-
in, you must
have an IBM HTTP Server for z/OS or OS/390 Version 5.3 configured as part of a z/OS
system

When the WebSphere HTTP

Plug
-
in for z/OS receives a browser request which targets a
servlet application in a WebSphere for z/OS V5.1 web container, it will re
-
direct the request to
the appropriate application server. The HTTP protocol request is directed to the internal
transpor
t port of the application server, and from here on it is processed in the same way as a
normal HTTP request that was directed straight to the application server

Web servers for distributed platforms can also have a WebSphere V5 plug
-
in installed. This
plug
-
in can be used to direct servlet requests to a suitable application server, which can be
located on another distributed system or on a WebSphere for z/OS V5.1 system.

©
Copyright IBM Corporation 2005
IBM zSeries
19
CR
Servlet
WEB
CONTAINER
SR
P xxx
z/OS HTTP
server
P xxx
Web
Server
WebSphere V5
distributed
plug
-
in
P xxx
Browser client
HTTP(S)
HTTP(S)
HTTP(S)
HTTP(S)
Internal
Transport
J2EE application server
ƒ
non
-
z/OS IBM HTTP Server
ƒ
Lotus Domino
ƒ
Apache
ƒ
iPlanet
ƒ
Microsoft IIS

WebSphere V5 plug
-
in for z/OS
HTTP server
ƒ
No more SCO support or GIOP
connection to web container
ƒ
Functionality for z/OS plugin now
equivalent to non
-
z/OS plugins
WebSphere
for z/OS V5
Plug
-
in
HTTP(S)
httpd.conf
plugin
-
cfg.xml
WebSphere V5 Plug
-
in for z/OS HTTP Server


Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
33

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.

There is a good reason to use the web server plug
-
in as an intermediary between the clie
nt
browser and the application server servlet. The WebSphere for z/OS V5.1 application
server
(
and other application servers) are not optimized for serving static files. So the client web
request is split into two parts. The servlet request is routed throu
gh the plug
-
in to the
application server which runs the servlet and formulates a response. When the HTTP HTML
response is returned, any static web files that are required for the response can be served
from the web server on which the plug
-
in is situated,
and if a proxy server is in place this
makes the process even faster.

Often the plug
-
in system is situated in the DMZ, and the targeted WebSphere application
server is behind a firewall in the secure intranet. This is easy to set up, as the HTTP protoc
ol
travels between fixed port addresses.

There are two configuration files used by the WebSphere HTTP
p
lug
-
in for z/OS
:



httpd.conf

-

IBM HTTP server configuration file



plugin
-
cfg.xml

-
The plug
-
in configuration file


Student Notebook


6
-
34

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.



















Figure
6
-
19

Turning on the Plug
-
in in httpd.conf

ESNEG1.0

Notes:

The name of the WebSphere for z/OS plug
-
in DLL
is
ihs390WAS50Plugin_http.so

and it
resides in the
<websphere install root>
/bin

directory. The full path name of the plug
-
in DLL is therefore
:


<websphere install root>
/bin/ihs390WAS50Plugin_http.so

To get the web server to recognize the new plug
-
in, you n
eed to insert a set of statements in
the web server configuration file httpd.conf. The statements are shown above and the format
is
:

ServerInit
<DLL
-
module
-
pathname>
:init_exit
<full pathname of plugin
-
cfg file>

Service
<webapp context root>

<DLL
-
module
-
pat
hname>
:service_exit

ServerTerm
<DLL
-
module
-
pathname>
:term_exit

©
Copyright IBM Corporation 2005
IBM zSeries
20
httpd.conf
ServerInit /usr/lpp/zWebSphere/V5R1M0/bin/>>
>>ihs390WAS50Plugin_http.so:init_exit /u/es68/web/plugin
-
cfg.xml
Service /PlantsByWebSphere/* /usr/lpp/zWebSphere/V5R1M0/>>
>>bin/ihs390WAS50Plugin_htt
p.so:service_exit
ServerTerm /usr/lpp/zWebSphere/V5R1M0/>>
>>bin/ihs390WAS50Plugin_http.so:term_exit
CONTEXT ROOT
http:// 10.31.227.198:8068 /PlantsByWebSphere /servlet/ShoppingS
ervlet
1
z/OS HTTP server
WebSphere
V5 Plug
-
in
plug
-
in
configuration
file
ƒ
Should request
be accepted?
ƒ
Which App
Server gets it?
2
3
HTTP
Internal
Transport
CR
P xxx
"business
as usual"
4
Turning on the Plug
-
in in httpd.conf


Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
35

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.

The ServerInit statement is used to start up the plug
-
in when the HTTP server is started. The
parameter passed is the name of the plug
-
in configuration file which supplies the options to
initi
alize the plug
-
in environment.

The
Service

statement is used to intercept an incoming browser request that should be
passed to the WebSphere application server. The string to the right of the Service keyword is
a template which is compared to the URL of th
e incoming request. If it matches, the request is
directed to the plug
-
in. The request URI must start with the servlet context root, so that is the
best value to put here. You will need as many service statements as you have unique context
roots.

The
Serve
rTerm

statement shuts down the plug
-
in when the web server is shut down.


Student Notebook


6
-
36

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.



















Figure
6
-
20

The Plug
-
in Configuration File

ESNEG1.0

Notes:

The plug
-
in configuration file is coded in XML format. The WebSphere for z/OS V5.1 HTTP
Server plug
-
in file is coded in EBCDIC still unlike WebSphere V5 distributed where it is always
an ASCII fil
e.

The full syntax for the file directives can be found in the WebSphere for z/OS Version 5
InfoCenter reference. This example shows the ones most often used.

Log Directive

s
pecifies the level of logging to be done for the plug
-
in message log (Trace,
Warn,

or Error), and the path name of the log file.

ServerCluster

is
a named group of one or more server definitions where all servers are
presumed to provide the same set of applications. Typically, these servers form a WebSphere
server cluster.

Server

names

a WebSphere for z/OS V5.1 application server present in WebSphere
configuration, and includes two transport definitions.

©
Copyright IBM Corporation 2005
IBM zSeries
21
<?xml version="1.0"?>
<Config>
<Log LogLevel="
Error
" Name="
/ILS/WAS510/APPCNFG/AppServer/logs/native.log
"/>
<ServerCluster Name="
Plant_group
">
<Server Name="
PlantServer
">
<Transport Hostname="
mvs21.ilsvpn.ibm.com
" Port="
9080
" Protocol="http"/>
<Transport Hostname="
mvs21.ilsvpn.ibm.com
" Port="
9443
" Protocol="https"/>
</Server> </ServerCluster>
<VirtualHostGroup Name="
web_vhosts
"/>
<VirtualHost Name="
* : 8068
"/>
</VirtualHostGroup>
<UriGroup Name="
plug_URIs
">
<Uri Name="
/PlantsByWebSphere*
"/ >
</UriGroup>
<Route ServerGroup="
Plant_group
" UriGroup="
plug_URIs
"
VirtualHostGroup="
web_vhost
s"/>
<
\
Config>
/u/es68/web/plugin
-
cfg.xml
http:// 10.31.227.198:8068 /PlantsByWebSphere /servlet/ShoppingS
ervlet
CONTEXT ROOT
VIRTUAL HOST MAPPING
The Plug
-
in Configuration File


Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
37

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.

Transport

d
efines the host name, port number, and protocol to be used for an internal
transport connection on the named server. The pl
ug
-
in uses these values to re
-
route an HTTP
request to the server that contains this transport definitions
.

VirtualHostGroup

is

a named group of one or more VirtualHost definitions
.

VirtualHost

definition consists of a “template” containing two fields sepa
rated by a colon. The
first field represents a host name and the second field is a port number. These fields are
compared to the host name and port on the incoming HTTP request. If they match, then the
request is acceptable to the plug
-
in
.

The host name ca
n be given as a fully qualified domain name, as an IP address, or the special
value “*” which means “match any host name”
.

Port number can be a port number or special value “*” which means “match any port”.

UriGroup

is

a named group of one or more Uri defi
nitions
.

Uri
definition
: n
ame field identifies a character string, usually starting with a “/”. This character
string is compared to the URI for the incoming request, starting at the first character in the
URI. If a match is made, this request is acceptabl
e to the plug
-
in. Typically URI values are
copies of context roots of web applications, but you can define more complex checking with
the help of wild card "*"
.

Route
:

t
his statement names a ServerGroup, a VirtualHost Group, and a Urigroup. It is used
to
direct an acceptable incoming request to a WebSphere for z/OS V5.1 application server.
How is this done
? W
ait till the following page
.


Student Notebook


6
-
38

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.



















Figure
6
-
21

How the Plug
-
in Works

ESNEG1.0

Notes:

For the purposes of discussing the visual, the plugin
-
cfg file
from

the previous page
is copied
below:

<ServerGroup Name="Plant_group">


<S
erver Name="PlantServer">


<Transport Hostname="mvs21.ilsvpn.ibm.com" Port="9080"
Protocol="http"/>


<Transport Hostname="mvs21.ilsvpn.ibm.com" Port="9443"
Protocol="https"/>


</Server Name> </ServerGroup


<VirtualHostGroup Name="web_vh
osts"/>


<VirtualHost Name=" * : 8068 "/>

</VirtualHostGroup>


<UriGroup Name="plug_URIs">


<Uri Name="/PlantsByWebSphere"/>

</UriGroup>


<Route ServerGroup="Plant_group" UriGroup="plug_URIs"


VirtualHostGroup="web_vhosts"/>



©
Copyright IBM Corporation 2005
IBM zSeries
22
Match on
virtual
host
Y
N
Match on
URI?
Y
Find Route
that includes
these names
N
N
found?
Forward URL
to app server
Y
Fail
request
http:// 10.31.227.198:8068/PlantsByWebSphere/servlet/ShoppingSer
vlet
VirtualHostGroup
name
web_vhosts
UriGroup
name
plug_URIs
ServerGroup
name
Plant_group
Plugin
Logic
How the Plug
-
in Works


Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
39

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.

In the visual, you can see the URL of the request that was passed to the HTTP server
.

The plug
-
in now searches the virtual host entries in all the virtual host groups looking for a
match with the host name and port name on the URL. It gets a
mat
ch on the only virtual host
definition in the file with the name “*:8068”. The plug
-
in remembers the name of the
VirtualHostGroup

that contains the matching entry, which is

web_vhosts
.

The next step the plug
-
in takes is to look for a match between a Uri en
try in the configuration
file and the request URI which is:

/PlantsByWebSphere/servlet/ShoppingServlet

The Uri name “/PlantsByWebSphere” matches the URI
-

by the way, this is also the context
root for the PlantsByWebSphere web application. The plug
-
in reme
mbers the name of the
UriGroup

that contains the matching entry, which is

plug_URIs
.

If either match is not successful, the plug
-
in fails the request.

If both matches are successful, the plug
-
in now wants to direct the request to a WebSphere
application s
erver. The plug
-
in searches the route statements defined in the configuration file,
looking for a statement which names the VirtualHostGroup and the UriGroup that the plug
-
in
has noted for this request. If it finds a Route statement that works, it reads th
e ServerGroup
value in the Route statement.

The ServerGroup will hold one or more server definitions. The plug
-
in now chooses a server
and routes the request to that server, using the HTTP or HTTPS port as needed by the
request. In our example there is on
ly a single server in the group Plant_group.

This is a very simple example with only one server choice. However the plug
-
in has some
sophisticated selection algorithms that it can use when there are multiple servers to choose
from. There are several more
statement types that can be put in the configuration that we
have not discussed. These can be used to set up selection algorithms for servers in particular
server groups. At the moment, WebSphere distributed is the bigger user of this functionality.

Student Notebook


6
-
40

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.



















Figure
6
-
22

Other Comments on Using the Plug
-
in

ESNEG1.0

Notes:


©
Copyright IBM Corporation 2005
IBM zSeries
23
server
BaseServer
Virtual Host: default_host
Host Alias: * : 9080
Host Alias: * : 9443
Host Alias: * : 8068
Server: BaseServer
Transport Handler:
end points = 9080, 9443 (SSL)
Appl: PlantsByWebSphere
http:// 10.31.227.198:8068 /PlantsByWebSphere /servlet/ShoppingS
ervlet
Application: PlantsByWebSphere
Web App name: PlantsByWebSphere WebApp
Web App module: PlantsByWebSphere.war
Virtual host:
default_host
Context root: /PlantsByWebSphere
WebSphere V5 Plug
-
in
http:// 10.31.227.198:9080 /PlantsByWebSphere /servlet/ShoppingS
ervlet
application
PlantsBy
WebSphere
ƒ
The virtual host mapped to by the application needs an alias to
match original URL
ƒ
The plugin can route requests to WebSphere servers running on a
different host
ƒ
Once the transport handler takes the request, it is handled in t
he same way as a request
that did not go through plug
-
in
Other Comments on Using the Plug
-
In


Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
41

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.



















Figure
6
-
23

Creating the plugin
-
cfg.xml File

ESNEG1.0

Notes:

There are two mechanisms p
rovided that can generate a plug
-
in configuration file based on
your current WebSphere for z/OS configuration
:

GenPluginCfg.sh

This is a USS shell script that can be executed from the OMVS command line. You can use
the parameters to tell WebSphere for z/OS

create a selective file. Specifying cell name only
builds a file for all servers in the cell, cell + node names builds a plug
-
in file for a specific node,
and adding a server name restricts the generated file to one server.

Tool writes file to location
<W
AS_HOME>
/AppServer/config/cells/plugin
-
cfg.xml

by
default unless you override it with parameter “
-
output.file.name”.

©
Copyright IBM Corporation 2005
IBM zSeries
24
Creating the plugin
-
cfg.xml File

Use the GenPluginCfg.sh utility

Run it as a command from the OMVS shell command line

Syntax:
GenPluginCfg.sh
-
cell.name
<cell>
-
node.name
<node>
-
server.name
<server>
-
output.file.name
<file_name>

Get help
GenPluginCfg.sh
-
help

From the administration tool console

Select:
Environment > Update Web Server
Plugin

Written to same default location as GenPluginCfg.sh
<WAS_HOME>
/AppServer/config/cells/plugin
-
cfg.xml

Other issues

Generation ignores manual updates made in existing files

Plug
-
in dynamically refreshes configuration after updates

Must set attribute TrustedProxy on for application server

Student Notebook


6
-
42

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.

Using the Administration Tool

If you select “Environment > Update Web Server Plugin2 from navigation panel, you will see a
panel that enab
les you to re
-
generate the plug
-
in configuration file.

Generated file always goes to the default location. Currently it only generates a cell wide
configuration file
.

If you have manually updated your live plug
-
in configuration file after generating it, th
e tool or
dialog ignores those changes and you will have to re
-
apply them manually.

In the plug
-
in file “<Config ...” statement, there is a parameter
RefreshInterval="nn"
t where
nn is seconds (default
-
60). When the plug
-
in is active, it will check to see i
f the current plug
-
in
configuration file has been modified every nn seconds. If the file is changed, the plug
-
in
dynamically rebuilds the plug
-
in configuration in storage and continues.

Finally, there is an essential change that must be made in the WebSphe
re for z/OS
configuration. A custom property “
TrustedProxy: true
” must be added either to the web
container section or the HTTP transports section of all application servers that work with the
plug
-
in. This enables application servers to tolerate extra pri
vate headers added to incoming
requests by the plug
-
in.

Details


Although the admin tool only generates cell
-
wide plug
-
in configuration files, they are
syntactically accurate XML. If you have added a new application, it may be worth re
-
generating

a cell
-
wide file from the tool, and then cutting and pasting the changed sections to your
existing live plug
-
in configuration file which might avoid the usual typos and finger problems.

The plug
-
in decides to see if it should check for plug
-
in file updates at th
e beginning of every
request. If more than 60 seconds have passed since the last time it received a request it will
then check the USS last modified date on the file. In other words, if the plug
-
in does not
receive any requests for 15 minutes, it will not
still be checking every 60 seconds. The next
request received kicks off the check.

This is the output from “GenPluginCfg.sh
-
help”.

Usage: GenPluginCfg ÝÝ
-
option.name optionValue¨...¨

Valid Options:

=
=============


-
config.root configroot_dir


(defaults to environment variable CONFIG_ROOT)


-
cell.name cell



(defaults to environment variable WAS_CELL)


-
node.name node


(defaults to environment variable WAS_NODE)


-
serv
er.name server


(required for single server plugin generation)


-
output.file.name file_name


(defaults to conf
igroot_dir/plugin
-
cfg.xml)


-
destination.root root


Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
43

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.


(install root of machine configuration will be used on)


-
destination.operating.system windows
/unix


(operating system of machine configuration will be used on)


-
debug yes/no


(defaults to no)



==============


Examples:


To generate a plugin config for all of the clusters in a cell:



GenPluginCfg
-
cell.name NetworkDeploymentCell


To generate a plugin config for a single server:


GenPluginCfg
-
cell.name BaseApplicationServerCell
-
node.name
serverNode

-
server.n
ame serverName


The TrustedProxy property is a change between V5.0 and V5.1. If you don’t set it, the plug
-
in
file gets an HTTP security error return code from the application server.


Student Notebook


6
-
44

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.



















Figure
6
-
24

The Edge Side Include (ESI) Cache

ESNEG1.0

Notes:

The Edge Side Include (ESI)

cache is now part of the WebSphere for z/OS HTTP server plug
-
in platform. It is a cache area in the virtual storage of the HTTP server address space that can
be used to cache output from WebSphere J2EE applications. If a client request is received by
the
plug
-
in, the plug
-
in searches the ESI cache first, and if a hit is obtained, the cached object
is returned straight to the client, reducing the load on the application servers.

Like all caches, the issue is what to put in the cache. The interesting part is

that it is
WebSphere for z/OS, not the plug
-
in, that makes the decision as to which objects should be
cached. When an application server sends objects back to the plug
-
in in response to a client
request, it will indicate on each object whether ESI should
cache it.

ESI is always told to cache static files (HTML, images, css style files
, and so on
)
.


ESI can also cache the output generated by JSPs or servlets, as well as responses to web
services requests. In this case, WebSphere for z/OS is instructed by
the application
©
Copyright IBM Corporation 2005
IBM zSeries
25
HTTP Server
Client
plug
-
in
ƒ
Try retrieve object
from cache first
ƒ
Send request
ƒ
Cache entry if server
tells ESI to do so
ƒ
Return response
ESI Cache
Application
Server
Webapp

ESI Cache will store

Static files (HTML,
images, style files)

Output from JSPs and
servlets

WebSphere tells ESI
what to cache

Only cache JSP or
servlet output if
application says so

Always caches static
files

Automatically switched on by default
-
explicitly switched on if
WebSphere generates plugin
-
cfg.xml

Complements FRCA caching for non
-
WebSphere objects
<Property Name="esiEnable" Value="
true
"/>
<Property Name="esiMaxCacheSize" Value="1024"/>
<Property Name="esiInvalidationMonitor" Value="false"/>
The Edge Side Include (ESI) Cache


Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
45

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.

developers as to which objects are cacheable
-

typically, these are objects that the developer
knows will not change for large periods of time.

If you generate a plug
-
in configuration file, it will always be generated with ESI caching
switc
hed on. The visual above shows the relevant statements. If you set the value of
esiEnable to false, caching is switched off (but if you remove statements it will still be switched
on by default).

Objects are deleted from the cache in two ways:



Deleted base
d on least recently referenced when cache is full



Deleted based on expiration of a time interval during which they are not referenced.

In general, ESI is probably good value for the money if you are serving static files for Web
applications from the applic
ation servers. It will provide significant improvement, similar to
FRCA support for web objects served from the HTTP server.

Details


The ESI caching is intimately tied to the WebSphere for z/OS dynamic caching
functionality. Dynamic caching, if switched
on, will cache the same types of objects that the
ESI cache holds, except that the Dynamic Cache is in the virtual storage of the application
server. In general, anything that happens to an object to the dynamic cache also happens to a
copy of this object
stored in the ESI cache. In WebSphere for Distributed platforms, if an
application instructs the application server to delete a copy of a specific option from the
dynamic cache, this instruction is propagated to the plug
-
in which takes the same action in t
he
ESI cache. So the applications control the presence and the currency of data in cached
objects. This option is not yet available to WebSphere for z/OS
.


A simple example of how an application decides on caching entries. Assume that a particular
servlet
request reads a table and returns information selected by the requester. The
application developer knows that the source data in the table is only changed once a day. The
application can then make the output for all requests to this server cacheable potent
ially for 24
hours. When the table is updated, the app is informed, and it instructs the dynamic cache (and
through it ESI) to throw away all output generated by this particular servlet in the cache. Note
that this does not stop the objects from being del
eted due to cache full situations
-

the
application will simply recreate the cached object on the next user request

The exception to the above is the caching of static files. Here, the application server
automatically indicates that all static files should

be cached in the ESI cache. No input from
any J2EE application is required to make this happen. An expiration timeout is set for all
cached static files, which has a default value of 300 seconds. If you want to change it, set JVM
command line parameter

-
Dcom.ibm.servlet.file.esi.timeOut
=nn”

for the
application servers
.

One final point
-

the dynamic cache functionality includes a monitoring tool by which an
administrator can manually manipulate specific entries in the dynamic and ESI caches. For
example, t
he administrator could decide to delete a number of static files from the cache
because he knew that the source had changed recently. This means however that
WebSphere for z/OS does not track updates to cache source.

Student Notebook


6
-
46

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.

Additional Information


A browser clie
nt request to run a servlet/JSP is received by the
Web server plug
-
in.

The request is directed to the WebSphere for z/OS V5 plug
-
in. The plug
-
in immediately sends
the request to the ESI processor, unless the ESI processor is disabled (it is enabled by
defa
ult).

If the ESI gets a cache hit, the cached servlet output is returned directly by the plug
-
in to the
client through the web server.

If a cache miss occurs, the plug
-
in adds a Surrogate
-
Capabilities header is to the HTTP
request header.

The request is fo
rwarded to the WebSphere for z/OS V5 application server.

If the dynamic servlet cache is enabled in the application server, the web container searches
the cache for the required entry. If it is not there, the servlet is executed and the output put in
the d
ynamic cache.

The metadata on the cache entry will indicate whether the response is edge cacheable
.

I
f not, the application server returns just the cached entry to the plug
-
in

I
f yes, the application server builds a Surrogate
-
Control header and returns it

to the
WebSphere for z/OS V5 plug
-
in. The value of the Surrogate
-
Control response header contains
the list of rules (basically the metadata all over again) which are used by the ESI processor in
order to generate the cache ID.

The application server retur
ns the response to the plug
-
in.

If the request has the Surrogate
-
Control response header, the cache entry is then stored in the
ESI cache, using the cache ID as the key.

For each ESI include tag in the body of the response, a new request is processed such
that
each nested include results in either a cache hit or another request forwarded to the
application server.

When all nested includes have been processed, the page is assembled and returned to the
client. The cache invalidation flow has not been shown on

the picture. When dynamic cache
services invalidate cache entries in the application server it will also forward invalidation
requests to the connected plug
-
in so that these can be applied to the ESI cache contents.



Student Notebook


© Copyright IBM Corp. 2005

Unit
6. The WebSphere V5 Web Container
6
-
47

Course

materials may not be reproduced in whole or in part

without the prior written permission of IBM.



















Figure
6
-
25

Unit Summary

ESNEG1.0

Notes:


Student Notebook


6
-
48

e
-
business for z/OS

© Copyright IBM Corp. 2005


Course materials may not be reproduced in whole or in part

without the prior written permission of IBM.