

<!--
The sip-app element is the root of the deployment descriptor for
a SIP servlet application
-->

<!ELEMENT sip-app (icon?, display-name?, description?, distributable?, context-param*, listener*, servlet*, servlet-mapping*, proxy-config?, session-config?,
resource-env-ref*, resource-ref*, security-constraint*, login-config?, security-role*,
env-entry*, ejb-ref*, ejb-local-ref*)>

<!--
The icon element contains small-icon and large-icon elements that
specify the file names for small and a large GIF or JPEG icon images
used to represent the parent element in a GUI tool.
-->

<!ELEMENT icon (small-icon?, large-icon?)>

<!--
The small-icon element contains the name of a file
containing a small (16 x 16) icon image. The file
name is a path relative to the root of the SAR.

The image may be either in the JPEG or GIF format.
The icon can be used by tools.

Example:

<small-icon>/employee-service-icon16x16.jpg</small-icon>
-->

<!ELEMENT small-icon (#PCDATA)>

<!--
The large-icon element contains the name of a file
containing a large (32 x 32) icon image. The file
name is a path relative to the root of the SAR.

The image may be either in the JPEG or GIF format.
The icon can be used by tools.

Example:

<large-icon>/employee-service-icon32x32.jpg</large-icon>
-->

<!ELEMENT large-icon (#PCDATA)>

<!--
The display-name element contains a short name that is intended to be
displayed by tools.  The display name need not be unique.

Example:

<display-name>Employee Self Service</display-name>
-->

<!ELEMENT display-name (#PCDATA)>

<!--
The description element is used to provide text describing the parent
element.  The description element should include any information that
SAR producer wants to provide to the consumer of
SAR (i.e., to the Deployer). Typically, the tools
used by SAR consumer will display the description
when processing the parent element that contains the description.
-->

<!ELEMENT description (#PCDATA)>

<!--
The distributable element, by its presence in a servlet application
deployment descriptor, indicates that this servlet application is
programmed appropriately to be deployed into a distributed servlet
container
-->

<!ELEMENT distributable EMPTY>

<!--
The context-param element contains the declaration of a servlet
application's servlet context initialization parameters.
-->

<!ELEMENT context-param (param-name, param-value, description?)>

<!--
The param-name element contains the name of a parameter. Each parameter
name must be unique in the servlet application.
-->

<!ELEMENT param-name (#PCDATA)>

<!--
The param-value element contains the value of a parameter.
-->

<!ELEMENT param-value (#PCDATA)>

<!--
The listener element indicates the deployment properties for a servlet application listener bean.
-->

<!ELEMENT listener (listener-class)>

<!--
The listener-class element declares a class in the application must be registered as 
a servlet application listener bean. The value is the fully qualified classname
of the listener class.
-->

<!ELEMENT listener-class (#PCDATA)>


<!--
The servlet element contains the declarative data of a servlet.
-->

<!ELEMENT servlet (icon?, servlet-name, display-name?, description?,
servlet-class, init-param*, load-on-startup?, run-as?, security-role-ref*)>

<!--
The servlet-name element contains the canonical name of the
servlet. Each servlet name is unique within the servlet application.
-->

<!ELEMENT servlet-name (#PCDATA)>

<!--
The servlet-class element contains the fully qualified class name
of the servlet.
-->

<!ELEMENT servlet-class (#PCDATA)>

<!--
The init-param element contains a name/value pair as an
initialization param of the servlet
-->

<!ELEMENT init-param (param-name, param-value, description?)>

<!--
The load-on-startup element indicates that this servlet should be
loaded (instantiated and have its init() called) on the startup 
of the servlet application. The optional contents of
these element must be an integer indicating the order in which
the servlet should be loaded. If the value is a negative integer, 
or the element is not present, the container is free to load the 
servlet whenever it chooses. If the value is a positive integer 
or 0, the container must load and initialize the servlet as the 
application is deployed. The container must guarantee that 
servlets marked with lower integers are loaded before servlets 
marked with higher integers. The container may choose the order 
of loading of servlets with the same load-on-start-up value.
-->

<!ELEMENT load-on-startup (#PCDATA)>

<!--
The servlet-mapping element defines a mapping between a servlet
and a pattern
-->

<!ELEMENT servlet-mapping (servlet-name, pattern)>

<!--
The different types of conditions supported.
-->

<!ENTITY % condition "and | or | not |
                      equal | contains | exists | subdomain-of">

<!--
A pattern is a condition: a predicate over the set of SIP requests.
-->

<!ELEMENT pattern (%condition;)>

<!--
An "and" condition is true if and only if all its constituent conditions
are true.
-->

<!ELEMENT and (%condition;)+>

<!--
An "or" condition is true if at least one of its constituent conditions
is true.
-->

<!ELEMENT or (%condition;)+>

<!--
Negates the value of the contained condition.
-->

<!ELEMENT not (%condition;)>

<!--
True if the value of the variable equals the specified literal value.
-->

<!ELEMENT equal (var, value)>

<!--
True if the value of the variable contains the specified literal value.
-->

<!ELEMENT contains (var, value)>

<!--
True if the specified variable exists.
-->

<!ELEMENT exists (var)>

<!--
-->

<!ELEMENT subdomain-of (var, value)>

<!--
Specifies a variable. Example:
  <var>request.uri.user</var>
-->

<!ELEMENT var (#PCDATA)>

<!--
Specifies a literal string value that is used to specify rules.
-->

<!ELEMENT value (#PCDATA)>

<!--
Specifies whether the "equal" test is case sensitive or not.
-->

<!ATTLIST equal ignore-case (true|false) "false">

<!--
Specifies whether the "contains" test is case sensitive or not.
-->

<!ATTLIST contains ignore-case (true|false) "false">

<!--
The proxy-config element configures proxy-related parameters.
-->

<!ELEMENT proxy-config (sequential-search-timeout?)>

<!--
The sequential-search-timeout element defines the default timeout
for sequential searches for all proxy operations performed by this
application. The specified timeout must be expressed in a whole
number of seconds. The container may override this value as a result
of its own local policy.
-->

<!ELEMENT sequential-search-timeout (#PCDATA)>

<!--
The session-config element defines the session parameters for
this servlet application.
-->

<!ELEMENT session-config (session-timeout?)>

<!--
The session-timeout element defines the default session timeout
interval for all application sessions created in this servlet
application. SipSessions have no timeout independent of that of the
containing application session. The lifetime of a SipSession is tied
to that of the parent application session. The specified timeout must
be expressed in a whole number of minutes.  If the timeout is 0 or
less, the container ensures the default behavior of sessions is never
to time out.
-->

<!ELEMENT session-timeout (#PCDATA)>

<!--
The resource-env-ref element contains a declaration of a servlet's
reference to an administered object associated with a resource
in servlet's environment.  It consists of an optional
description, the resource environment reference name, and an
indication of the resource environment reference type expected by
servlet code.

Example:

<resource-env-ref>
    <resource-env-ref-name>jms/StockQueue</resource-env-ref-name>
    <resource-env-ref-type>javax.jms.Queue</resource-env-ref-type>
</resource-env-ref>
-->

<!ELEMENT resource-env-ref (description?, resource-env-ref-name, 
resource-env-ref-type)>

<!-- 
The resource-env-ref-name element specifies the name of a resource
environment reference; its value is the environment entry name used in
servlet code.  The name is a JNDI name relative to the
java:comp/env context and must be unique within a servlet application.
 -->

<!ELEMENT resource-env-ref-name (#PCDATA)>

<!-- 
The resource-env-ref-type element specifies the type of a resource
environment reference.  It is the fully qualified name of a Java
language class or interface.
-->

<!ELEMENT resource-env-ref-type (#PCDATA)>

<!--
The resource-ref element contains a declaration of a servlet's
reference to an external resource. It consists of an optional
description, the resource manager connection factory reference name,
the indication of the resource manager connection factory type
expected by servlet code, the type of authentication
(Application or Container), and an optional specification of the
shareability of connections obtained from the resource (Shareable or
Unshareable).

Example:

    <resource-ref>
	<res-ref-name>jdbc/EmployeeAppDB</res-ref-name>
	<res-type>javax.sql.DataSource</res-type>
	<res-auth>Container</res-auth>
	<res-sharing-scope>Shareable</res-sharing-scope>
    </resource-ref>

-->

<!ELEMENT resource-ref (description?, res-ref-name, res-type, res-auth, res-sharing-scope?)>

<!--
The res-ref-name element specifies the name of the resource
factory reference name.
-->

<!ELEMENT res-ref-name (#PCDATA)>

<!--
The res-ref-name element specifies the name of a resource manager
connection factory reference.  The name is a JNDI name relative to the
java:comp/env context.  The name must be unique within servlet application.
-->

<!ELEMENT res-type (#PCDATA)>

<!--
The res-auth element specifies whether the servlet code signs
on programmatically to the resource manager, or whether the Container
will sign on to the resource manager on behalf of the servlet. In the
latter case, the Container uses information that is supplied by the
Deployer.

The value of this element must be one of the two following:

	<res-auth>Application</res-auth>
	<res-auth>Container</res-auth>
-->

<!ELEMENT res-auth (#PCDATA)>

<!-- 
The res-sharing-scope element specifies whether connections obtained
through the given resource manager connection factory reference can be
shared. The value of this element, if specified, must be one of the
two following:

	<res-sharing-scope>Shareable</res-sharing-scope>
	<res-sharing-scope>Unshareable</res-sharing-scope>

The default value is Shareable.
-->

<!ELEMENT res-sharing-scope (#PCDATA)>

<!--
The security-constraint element is used to associate security
constraints with one or more servlet resource collections
-->

<!ELEMENT security-constraint (display-name?, resource-collection+,
proxy-authentication?, auth-constraint?, user-data-constraint?)>

<!--
The resource-collection element is used to identify a subset
of the resources and SIP methods on those resources within a servlet
application to which a security constraint applies. If no SIP methods
are specified, then the security constraint applies to all SIP
methods.
-->

<!ELEMENT resource-collection (resource-name, description?,
servlet-name*, sip-method*)>

<!--
The resource-name contains the name of this resource collection
-->

<!ELEMENT resource-name (#PCDATA)>

<!--
The sip-method contains an SIP method (INVITE | BYE |...)
-->

<!ELEMENT sip-method (#PCDATA)>

<!--
The presence of the proxy-authentication element indicates to the
container that it must challenge the user agent with a 407 (Proxy
Authentication Required) response status code when authenticating an
incoming request. If not present a 401 (Unauthorized) status code is
used.
-->

<!ELEMENT proxy-authentication EMPTY>

<!--
The user-data-constraint element is used to indicate how data
communicated between the client and container should be protected
-->

<!ELEMENT user-data-constraint (description?, transport-guarantee)>

<!--
The transport-guarantee element specifies that the communication
between client and server should be NONE, INTEGRAL, or
CONFIDENTIAL. NONE means that the application does not require any
transport guarantees. A value of INTEGRAL means that the application
requires that the data sent between the client and server be sent in
such a way that it can't be changed in transit. CONFIDENTIAL means
that the application requires that the data be transmitted in a
fashion that prevents other entities from observing the contents of
the transmission. In most cases, the presence of the INTEGRAL or
CONFIDENTIAL flag will indicate that the use of SSL is required.
-->

<!ELEMENT transport-guarantee (#PCDATA)>

<!--
The auth-constraint element indicates the user roles that should
be permitted access to this resource collection. The role-name 
used here must either correspond to the role-name of one of the 
security-role elements defined for this servlet application, or be 
the specially reserved role-name "*" that is a compact syntax for 
indicating all roles in the servlet application. If both "*" and 
rolenames appear, the container interprets this as all roles.
If no roles are defined, no user is allowed access to the portion of
the servlet application described by the containing security-constraint.
The container matches role names case sensitively when determining 
access.
-->

<!ELEMENT auth-constraint (description?, role-name*)>

<!--
The role-name element contains the name of a security role.
-->

<!ELEMENT role-name (#PCDATA)>

<!--
The login-config element is used to configure the authentication
method that should be used, the realm name that should be used for
this application, and the attributes that are needed by the form login
mechanism.
-->

<!ELEMENT login-config (auth-method?, realm-name?)>

<!--
The realm name element specifies the realm name to use in HTTP
Basic authorization
-->

<!ELEMENT realm-name (#PCDATA)>

<!--
The auth-method element is used to configure the authentication
mechanism for the SIP servlet application. As a prerequisite to gaining 
service from any SIP servlet which is protected by an authorization
constraint, a user must have authenticated using the configured
mechanism. Legal values for this element are "BASIC", "DIGEST",
or "CLIENT-CERT".
-->

<!ELEMENT auth-method (#PCDATA)>

<!--
The security-role element contains the declaration of a security
role which is used in the security-constraints placed on the servlet
application.
-->

<!ELEMENT security-role (description?, role-name)>

<!--
The security-role-ref element defines a mapping between the name of 
role called from a Servlet using 
isUserInRole(String name) and the name of a security role defined 
for the servlet application. For example, 
to map the security role reference "FOO" to the security role 
with role-name "manager" the sytax would 
be:

<security-role-ref>
  



<role-name>FOO</role-name>
  
<role-link>manager</manager>
</security-role-ref>

In this case if the servlet called by a user belonging to the "manager" 
security role made the API call 
isUserInRole("FOO") the result would be true.
Since the role-name "*" has a special meaning for authorization 
constraints, its value is not permitted here.
-->

<!ELEMENT security-role-ref (description?, role-name, role-link)>

<!--
The role-link element is used to link a security role reference
to a defined security role. The role-link element must contain the
name of one of the security roles defined in the security-role
elements.
-->

<!ELEMENT role-link (#PCDATA)>

<!--
The env-entry element contains the declaration of a servlet application's
environment entry. The declaration consists of an optional
description, the name of the environment entry, and an optional
value.  If a value is not specified, one must be supplied
during deployment.
-->

<!ELEMENT env-entry (description?, env-entry-name, env-entry-value?,
env-entry-type)>

<!--
The env-entry-name element contains the name of a servlet applications's
environment entry.  The name is a JNDI name relative to the
java:comp/env context.  The name must be unique within a servlet application.

Example: 

<env-entry-name>minAmount</env-entry-name>
-->

<!ELEMENT env-entry-name (#PCDATA)>

<!--
The env-entry-value element contains the value of A_COMPONENT's
environment entry. The value must be a String that is valid for the
constructor of the specified type that takes a single String
parameter, or for java.lang.Character, a single character.

Example: 

<env-entry-value>100.00</env-entry-value>
-->

<!ELEMENT env-entry-value (#PCDATA)>

<!--
The env-entry-type element contains the fully-qualified Java type of
the environment entry value that is expected by THE_COMPONENT's
code.

The following are the legal values of env-entry-type:

	java.lang.Boolean
	java.lang.Byte
	java.lang.Character
	java.lang.String
	java.lang.Short
	java.lang.Integer
	java.lang.Long
	java.lang.Float
	java.lang.Double
-->

<!ELEMENT env-entry-type (#PCDATA)>

<!--
The ejb-ref element is used for the declaration of a reference to
an enterprise bean's home. The declaration consists of:

	- an optional description
	- the EJB reference name used in the code of
	  the servlet that's referencing the enterprise bean
	- the expected type of the referenced enterprise bean
	- the expected home and remote interfaces of the referenced
	  enterprise bean
	- optional ejb-link information, used to specify the referenced
	  enterprise bean
 
-->

<!ELEMENT ejb-ref (description?, ejb-ref-name, ejb-ref-type, home, 
remote, ejb-link?)>

<!--
The ejb-ref-name element contains the name of an EJB reference. The
EJB reference is an entry in the servlet's environment and is
relative to the java:comp/env context.  The name must be unique
within the servlet application.

It is recommended that name is prefixed with "ejb/".

Example: 

<ejb-ref-name>ejb/Payroll</ejb-ref-name>
-->

<!ELEMENT ejb-ref-name (#PCDATA)>

<!-- The ejb-ref-type element contains the expected type of the 
referenced enterprise bean. The ejb-ref-type element must be one of the following:

   <ejb-ref-type>Entity</ejb-ref-type>
   <ejb-ref-type>Session</ejb-ref-type>
-->

<!ELEMENT ejb-ref-type (#PCDATA)>

<!--
The home element contains the fully-qualified name of the enterprise
bean's home interface.

Example:

<home>com.aardvark.payroll.PayrollHome</home>
-->

<!ELEMENT home (#PCDATA)>

<!--
The remote element contains the fully-qualified name of the enterprise
bean's remote interface.

Example: 

<remote>com.wombat.empl.EmployeeService</remote>
-->

<!ELEMENT remote (#PCDATA)>

<!--
The ejb-link element is used in the ejb-ref or ejb-local-ref
elements to specify that an EJB reference is linked to another
enterprise bean.

The value of the ejb-link element must be the ejb-name of an
enterprise bean in the same J2EE application unit.

The name in the ejb-link element may be composed of a
path name specifying the ejb-jar containing the referenced enterprise
bean with the ejb-name of the target bean appended and separated from
the path name by "#".  The path name is relative to the SAR
containing the servlet application that is referencing the enterprise bean.
This allows multiple enterprise beans with the same ejb-name to be
uniquely identified.

Examples: 

	<ejb-link>EmployeeRecord</ejb-link>

	<ejb-link>../products/product.jar#ProductEJB</ejb-link>

-->

<!ELEMENT ejb-link (#PCDATA)>


<!--
The ejb-local-ref element is used for the declaration of a reference to
an enterprise bean's local home. The declaration consists of:

	- an optional description
	- the EJB reference name used in the code of THE_COMPONENT
	  that's referencing the enterprise bean
	- the expected type of the referenced enterprise bean
	- the expected local home and local interfaces of the referenced
	  enterprise bean
	- optional ejb-link information, used to specify the referenced
	  enterprise bean
-->

<!ELEMENT ejb-local-ref (description?, ejb-ref-name, ejb-ref-type,
		local-home, local, ejb-link?)>

<!-- 

The local element contains the fully-qualified name of the
enterprise bean's local interface. 

Used by ejb-local-ref

-->
<!ELEMENT local (#PCDATA)>

<!-- 

The local-home element contains the fully-qualified name of the
enterprise bean's local home interface. 

Used by ejb-local-ref
-->
<!ELEMENT local-home (#PCDATA)>




<!--
The run-as element, if defined for a servlet, overrides the security 
identity used to call an EJB
by that servlet in this servlet application. The role-name is one of the 
security roles already
defined for this servlet application.

Used by: <servlet>
-->
<!ELEMENT run-as (description?, role-name)>



<!--
The ID mechanism is to allow tools to easily make tool-specific
references to the elements of the deployment descriptor. This allows
tools that produce additional deployment information (i.e information
beyond the standard deployment descriptor information) to store the
non-standard information in a separate file, and easily refer from
these tools-specific files to the information in the standard sip-app
deployment descriptor.
-->

<!ATTLIST sip-app id ID #IMPLIED>
<!ATTLIST icon id ID #IMPLIED>
<!ATTLIST small-icon id ID #IMPLIED>
<!ATTLIST large-icon id ID #IMPLIED>
<!ATTLIST display-name id ID #IMPLIED>
<!ATTLIST description id ID #IMPLIED>
<!ATTLIST distributable id ID #IMPLIED>
<!ATTLIST context-param id ID #IMPLIED>
<!ATTLIST param-name id ID #IMPLIED>
<!ATTLIST param-value id ID #IMPLIED>
<!ATTLIST listener id ID #IMPLIED>
<!ATTLIST listener-class id ID #IMPLIED>
<!ATTLIST servlet id ID #IMPLIED>
<!ATTLIST servlet-name id ID #IMPLIED>
<!ATTLIST servlet-class id ID #IMPLIED>
<!ATTLIST init-param id ID #IMPLIED>
<!ATTLIST load-on-startup id ID #IMPLIED>
<!ATTLIST servlet-mapping id ID #IMPLIED>
<!ATTLIST proxy-config id ID #IMPLIED>
<!ATTLIST sequential-search-timeout id ID #IMPLIED>
<!ATTLIST session-config id ID #IMPLIED>
<!ATTLIST session-timeout id ID #IMPLIED>
<!ATTLIST resource-env-ref id ID #IMPLIED>
<!ATTLIST resource-env-ref-name id ID #IMPLIED>
<!ATTLIST resource-env-ref-type id ID #IMPLIED>
<!ATTLIST resource-ref id ID #IMPLIED>
<!ATTLIST res-ref-name id ID #IMPLIED>
<!ATTLIST res-type id ID #IMPLIED>
<!ATTLIST res-auth id ID #IMPLIED>
<!ATTLIST res-sharing-scope id ID #IMPLIED>
<!ATTLIST security-constraint id ID #IMPLIED>
<!ATTLIST resource-collection id ID #IMPLIED>
<!ATTLIST resource-name id ID #IMPLIED>
<!ATTLIST sip-method id ID #IMPLIED>
<!ATTLIST proxy-authentication id ID #IMPLIED>
<!ATTLIST user-data-constraint id ID #IMPLIED>
<!ATTLIST transport-guarantee id ID #IMPLIED>
<!ATTLIST auth-constraint id ID #IMPLIED>
<!ATTLIST role-name id ID #IMPLIED>
<!ATTLIST login-config id ID #IMPLIED>
<!ATTLIST realm-name id ID #IMPLIED>
<!ATTLIST auth-method id ID #IMPLIED>
<!ATTLIST security-role id ID #IMPLIED>
<!ATTLIST security-role-ref id ID #IMPLIED>
<!ATTLIST role-link id ID #IMPLIED>
<!ATTLIST env-entry id ID #IMPLIED>
<!ATTLIST env-entry-name id ID #IMPLIED>
<!ATTLIST env-entry-value id ID #IMPLIED>
<!ATTLIST env-entry-type id ID #IMPLIED>
<!ATTLIST ejb-ref id ID #IMPLIED>
<!ATTLIST ejb-ref-name id ID #IMPLIED>
<!ATTLIST ejb-ref-type id ID #IMPLIED>
<!ATTLIST home id ID #IMPLIED>
<!ATTLIST remote id ID #IMPLIED>
<!ATTLIST ejb-link id ID #IMPLIED>
<!ATTLIST ejb-local-ref id ID #IMPLIED>
<!ATTLIST local-home id ID #IMPLIED>
<!ATTLIST local id ID #IMPLIED>
<!ATTLIST run-as id ID #IMPLIED>
<!ATTLIST pattern id ID #IMPLIED>
<!ATTLIST and id ID #IMPLIED>
<!ATTLIST or id ID #IMPLIED>
<!ATTLIST not id ID #IMPLIED>
<!ATTLIST equal id ID #IMPLIED>
<!ATTLIST contains id ID #IMPLIED>
<!ATTLIST exists id ID #IMPLIED>
<!ATTLIST subdomain-of id ID #IMPLIED>
<!ATTLIST var id ID #IMPLIED>
<!ATTLIST value id ID #IMPLIED>

