Fragment Files

Fragment naming conventions

Fragments must be named using the format:

FRAMEWORK.FRAGMENT_NAME.web.xml.part

where FRAMEWORK is the name of the framework to which the fragment belongs, and FRAGMENT_NAME is a unique fragment name within the given framework. There are no limitations with regard to character usage.

Fragment overrides

You can override items defined in the root web.xml file by defining a fragment containing element with the same name.

The WAR Utility will display a warning message when merging the fragment to web.xml, but will keep the one defined last.

Enhanced fragments

It is possible to describe how you want a fragment to be processed using enhanced fragments. Start by using the following DOCTYPE declaration:

<!DOCTYPE web-app-fragment PUBLIC
"-//Dassault Systemes, Inc.//DTD Web Application Fragment 0.1//EN"
"http://3ds.com/dtd/web-app-fragment_0_1.dtd"
[<!ENTITY % w PUBLIC
"'-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.suncom/dtd/web-app_2_3.dtd" > %w;]>

Custom profiles

Custom profiles allow a fragment to be merged into web.xml on demand. To define a custom profile, use the following:

<profiles>
   <custom name="mykey"/>
</profiles>

A fragment with this profile will only be included upon request by launching the WAR Utility with the extra option, as follows:

PLATFORM/code/command/war_setup.sh -extra:mykey

Fragment priorities

Fragment priorities allow a fragment to be included in web .xml in a particular order. To include one fragment before another, use the priority attribute, as follows:

<web-app-fragment priority="i"/>

where i is an integer. The lower the integer, the higher the priority. For example, a fragment with a priority of 10 will be merged before another with a priority of 15.

Servlet 3.0 web-app and web-fragment ordering

Servlet 3.0 web.xml ordering syntax is supported. (For more information, see the Servlet 3.0 specification , Section 8.2.2 Ordering of web.xml and web-fragment.xml.)

XSLT validation is not supported. You must replace any xmlns/xsi declaration with the DOCTYPE declarations described in the next sections.

web-fragments

First, you must use the following DOCTYPE declaration for a web-fragment:

<!DOCTYPE web-fragment PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 3.0//EN"
"http://3ds.com/dtd/web-fragment_3_0.dtd">

To take advantage of web ordering, you can name your fragment (using the same naming convention as for fragment file names), as follows:

<web-fragment>
   <name>FRAMEWORK.FRAGMENT_NAME</name>
</web-fragment>

As explained in the Servlet 3.0 specification , you can also use the ordering tag, for example, as folllows:

<ordering>
   <after><name>A</name></after>
   <before><name>C</name></before>
</ordering>

web-app

You can specify an absolute ordering through the root web.xml file by using the following DOCTYPE declaration:

<!DOCTYPE web-fragment PUBLIC "-//DTD Web Application 3.0//EN"
"http://3ds.com/dtd/web-app_3_0.dtd">

You can use the absolute-ordering tag, for example, as follows:

<absolute-ordering>
   <name>A</name>
   <others/>
   <name>C</name>
</absolute-ordering>

Examples

In the following examples, a servlet and a filter are declared separately. However, both can also be merged in the same fragment, as long as they comply with the root XML schema.

Fragment creation

First, check which XML schema the root web.xml is using. You can read it in the file:

FRAMEWORK/CNext/install/ematrixwarutil/web.xml

The following is an example of the first two lines:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">

This means that you must conform to the following XML schema (in this case, a DTD) when writing fragments:

http://java.sun.com/dtd/web-app_2_3.dtd (-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN)

In your framework, create a fragment called FRAMEWORK.FRAGMENT_NAME.web.xml.part (see Fragment naming conventions), as follows:
```
FRAMEWORK/CNext/install/warutil/fragment/FRAMEWORK.FRAGMENT_NAME.web.xml.part
```

Then you can start editing the basic layout based on the root web.xml, for example:

<?xml version "1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC "-??Sun Microsystems, Inc.//DTD web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
   <web-app id="WebApp_1">
   </web-app>

Servlet declaration

Create the fragment (see Fragment creation).

Within the fragment web-app tag, write your servlet declaration. For example:

<servlet id="VPLMServlet_1">
   <servlet-name>SidlChunkedServlet</servlet-name>
   <servlet-class>com.dassault_systemes.m1sidlserver.m1sidlservlet.SidlChunkedServlet</servlet-class>
</servlet>
<servlet id="VPLMServlet_2">
   <servlet-name>SidlServlet</servlet-name>
   <servlet-class>com.dassault_systemes.m1sidlserver.m1sidlservlet.SidlServlet</servlet-class>
</servlet>
<servlet id="VPLMServlet_3">
   <servlet-name>webservice</servlet-name>
   <servlet-class>com.matrixone.jsystem.ws.impl.SoapServlet</servlet-class>
</servlet>
<servlet-mapping id="VPLMServletMapping_1">
   <servlet-name>SidlChunkedServlet</servlet-name>
   <url-pattern>/SidlChunked/*</url-pattern>
</servlet-mapping>
<servlet-mapping id="VPLMServletMapping_2">
   <servlet-name>SidlServlet</servlet-name>
   <url-pattern>/Sidl/*</url-pattern>
</servlet-mapping>
<servlet-mapping id="VPLMServletMapping_3">
   <servlet-name>webservice</servlet-name>
   <url-pattern>/webservice/*</url-pattern>
</servlet-mapping>

Filter declaration

Create the fragment (see Fragment creation).

Within the fragment web-app tag, write your filter declaration. For example:

<filter>
   <filter-name>StaticContentCachingFilter</filter-name>
   <filter-class>com.matrixone.servlet.StaticContentCachingFilter</filter-class>
   <init-param>
      <param-name>ematrixcache-control.ResourceLifetime</param-name>
      <param-value>7d</param-value>
   </init-param>
</filter>
<filter-mapping>
   <filter-name>StaticContentCachingFilter</filter-name>
   <url-pattern>*.html</url-pattern>
</filter-mapping>