Deploying using Web Fragments (web-fragment.xml)

Annotations were introduced to reduce the burden of Application assemblers who would otherwise have to combine every developer’s configuration details into the web.xml file. Thus annotations allow for pluggability of the code by allowing developers to specify configurations on their own classes and hence application assemblers would not have to add them to the web.xml file. We can still use web.xml to override any of the configuration given by an annotation. We may also use the web.xml element metadata-complete with a value of true to ignore any other configuration details such as annotations or web fragments.

Web fragments are xml files that will have part of the configurations of a web.xml. There can be many web fragments, and when the application is deployed container will combine all the fragments and will treat it like a single web.xml. Similar to annotations, now developers can write web fragments for their modules and application assemblers would not have to add them to the web.xml file. We can override annotation behavior with a web fragment or web.xml. Container will first process web.xml and then based on any order defined (if any) process web fragments and finally will process annotations for any metadata that is not already defined in web fragment or web.xml. You may also specify the order of invocation of web fragments from within the web fragment.

When annotations were already there to support modularity, why you need a web fragment? Not everything which can be defined using a web.xml can be configured using annotations. This includes most JSP related configurations and the welcome-lists. You may also want to quickly override some of the details configured as annotations without recompiling the code, which can be done through xmls like web.xml or web fragments. However using a web.xml to override the annotation behavior will again increase the overhead of application assemblers. So web fragments are a better solution for overriding annotation behavior and can be supplied by the same developers itself. Another advantage of web fragments over annotations is that ordering of components using annotations is not defined, whereas we can specify order for web fragments.

 

Syntax and rules for defining web fragments

  1. Each fragment must reside in its own JAR, and within the JAR it should be present in a file named web-fragment.xml in the META-INF folder of the Jar.
  2. The JAR containing a web fragment should be deployed into the WEBINF/lib directory of the web application.
  3. The root element of a web fragment is <web-fragment> and it may contain any sub elements of <web-app> element in the DD (web.xml).
  4. Each web fragment may contain a name element. The name element should be unique across all web fragments and there should not be any circular references or loops, or container will abort application deployment with a meaningful error. This name will be used for any ordering of the web fragments.
  5. You can specify the order of web fragments from within a web.xml using the element <absolute-ordering>. You can specify the order of web fragments from within a web fragment itself using the element <ordering>. Within a web.xml or a web fragment, elements are loaded in the order they are declared. Ordering of components using annotations is not defined. Ordering of web fragments are also not defined by default, but they can be ordered using <absolute-ordering> in a DD or <ordering> element in a web fragment.
  6. The web.xml element metadata-complete with a value of true will ignore any other configuration details such as annotations or web fragments. If the value of this is true or this element is omitted, it will get the configuration details from web fragments and annotations. However, if any of the web fragment has a value of false for element metadata-complete, the web fragment and its annotations will be ignored.
  7. Configurations from multiple descriptors will be merged (web.xml or fragments). If the element can take multiple values, the value will be a union and if there is a conflict between a web fragment and web.xml, web.xml will take precedence. However, if there is a conflict between two fragments, error is raised.
    • Elements like welcome-file-list and locale-encoding-mapping-list will have their values merged.
    • For filters and servlets, the value declared in the DD/fragment will only override the value of any duplicate named parameters, and rest will be merged.
    • The url-pattern and DispatcherType, annotation value is strictly overridden by DD/fragment without any merge.
    • Elements like session-config, jsp-config and login-config may only appear at most once across web.xml and all web fragments.
    • <init-param> and <mime-mapping> may only be declared once for the given <param-name> or extension respectively or an error will be raised.
  8. An application is considered distributable if web.xml and all its fragments are marked as <distributable>.

 

Ordering web fragments

Within a web.xml or a web fragment, elements are loaded in the order they are declared. Ordering of components using annotations is not defined. Ordering of web fragments are also not defined by default, but they can be ordered using <absolute-ordering> in a DD or <ordering> element in a web fragment.

You can specify the order of web fragments from within a web fragment itself using the element <ordering>. <ordering> has two subelements <before> and <after>, and they can contain any <name> elements and fragments declared inside <before> will be loaded before this fragment and  fragments declared inside <after> will be loaded after this fragment. Both subelements <before> and <after> may also contain an <others/> element which will refer to all other elements not explicitly named.

<web-fragment>

  <name>fragment2</name>

  <ordering>

    <before>

    <name>fragment3</name>

    <others/>

    </before>

    <after>

    <name>fragment1</name>

    </after>

  </ordering>

<web-fragment>

You can specify the order of web fragments from within a web.xml using the element <absolute-ordering>. Order specified by <absolute-ordering> will override any conflicting ordering specified by <ordering>.

The <absolute-ordering> may contain <name> elements and the <others/> element. The <others/> element which will refer to all other elements not explicitly named. If an <others/> element is not present and an element is not explicitly defined, that fragment configuration is completely ignored.

<web-app>

  <absolute-ordering>

    <name>fragment1<name>

    <name>fragment2<name>

    <others/>

    <name>fragment3<name>

  </absolute-ordering>

</web-app>

You will be clearer about web fragments once you do the demo (next note.)

Search the Web

Custom Search

Searches whole web. Use the search in the right sidebar to search only within javajee.com!!!