Fragment Files

Use of fragments makes it possible to specify how to use a component using the web.xml standard format for:

Servlets
Servlet mapping
Filters
Filter mapping

Fragments are placed on the SCM path FRAMEWORK\CNEXT\install\warutil\fragment, where FRAMEWORK is the development framework of the component.
web.xml fragments

Fragments should comply with the same XML schema as the main web.xml file. The merger checks the validity of fragments before merging them. If one fragment is invalid, the entire install will fail.

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>