Servlet: Deployment Descriptor (DD)

DD ก็คือ XML ไฟล์ที่กำหนดการ deploy Servlet สำหรับ Web Container หรือ DD ก็คือ web.xml นะเอง

ตัวอย่างของ DD อย่างง่ายๆ

<web-app version="2.4"
xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

  <context-param>
    <param-name>param</param-name>
    <param-value>parameter value</param-value>
  </context-param>
  [ <context-param> ...parameter name-value pair as above... </context-param> ]

  <listener>
    <listener-class>package.class</listener-class>
  </listener>

  <session-config>
    <session-timeout>10</session-timeout>
  </session-config>

  <servlet>
    <servlet-name>Internal Name</servlet-name>
    <servlet-class>package.ServletClass</servlet-class> | <jsp-file>path/file.jsp</jsp-file>
    <load-on-startup>1<load-on-startup/>

    <init-param>
      <param-name>param</param-name>
      <param-value>parameter value</param-value>
    </init-param>
    [ <init-param> ...parameter name-value pair... <init-param> ]...

    <security-role-ref>
      <role-name>Manager</role-name>
      <role-link>Admin</role-line>
    </security-role-ref>
  </servlet>

  <servlet-mapping>
    <servlet-name>Internal Name</servlet-name>
    <url-pattern>/Public.do</url-pattern>
  </servlet-mapping>

  <jsp-config>
    <jsp-property-group>
      <url-pattern>*.jsp</url-pattern>
      <el-ignored>[ true | false ]</el-ignored>
      <scripting-invalid>[ true | false ]</scripting-invalid>
    </jsp-property-group>

    <taglib>
      <taglib-uri>randomThing</taglib-uri>
      <taglib-location>/WEB-INF/myFunctions.tld</taglib-location>
    </taglib>
  </jsp-config>

  <!-- filter config -->
  <filter>
    <filter-name>LogRequest</filter-name>
    <filter-class>package.Filter</filter-class>

    <init-param>
      <param-name>param</param-name>
      <param-value>parameter value</param-value>
    </init-param>
    [ <init-param> ...parameter name-value pair... <init-param> ]...
  </filter>

  <filter-mapping>
    <filter-name>LogRequest</filter-name>
    <url-pattern>/path/*</url-pattern> | <servlet-name>AnyRequest</servlet-name>
    <dispatcher> REQUEST | INCLUDE | FORWARD | ERROR </dispatcher>
    [ <dispatcher> REQUEST | INCLUDE | FORWARD | ERROR </dispatcher> ]...
  </filter-mapping>

  <!-- declare welcome file -->
  <welcome-file-list>
    <welcome-file>index.html</welcome-file>
    [ <welcome-file>index.html</welcome-file> ]...
  </welcome-file-list>

  <!-- declare to catch all error, but you can change to catch only some exceptions -->
  <error-page>
    <exception-type>java.lang.Throwable</exception-type>
    <location>/ErrorPage.jsp</location>
  </error-page>

  <!-- This is another way to catch error by status code -->
  <error-page>
    <error-code>404</error-code>
    <location>/ErrorNotFound.jsp</location>
  </error-page>

  <!-- external resource related -->
  <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>
  <resource-ref>
    <res-ref-name>ECC</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth> APPLICATION | CONTAINER </res-auth>
    <res-sharing-scope> Shareable | Unshareable </res-sharing-scope>
  </resource-ref>

  <!-- EJB related -->
  <ejb-local-ref>
    <ejb-ref-name>JNDI lookup name (such as ejb/Customer)</ejb-ref-name>
    <ejb-ref-type> Entity | Session </ejb-ref-type>
    <local-home>package.Class</local-home>
    <local>package.Class</local>
  </ejb-local-ref>

  <ejb-ref>
    <ejb-ref-name>JNDI lookup name (such as ejb/Customer)</ejb-ref-name>
    <ejb-ref-type> Entity | Session </ejb-ref-type>
    <home>package.Class</home>
    <remote>package.Class</remote>
  </ejb-ref>

  <env-entity>
    <env-entry-name>JNDI lookup name (such as rates/discountRate)</env-entry-name>
    <env-entry-type>java.lang.Integer</env-entry-type>
    <env-entry-value>10<env-entry-value>
  </env-entity>

  <!-- mine-type mapping -->
  <mime-mapping>
    <extension>mgp</extension>
    <mime-type>video/mpeg</mime-type>
  </mime-mapping>

  <!-- constraint resource -->
  <security-constraint>

    <web-resource-collection>
      <web-resource-name>some name</web-resource-name>
      <description>explain about tht resource</description>
      <url-pattern>/Public.do</url-pattern>
      [ <url-pattern>/Path/resource</url-pattern> ]...

      <http-method>GET | POST | PUT | TRACE | DELETE | HEAD | OPTION</http-method>
      [ <http-method>GET | POST | PUT | TRACE | DELETE | HEAD | OPTION</http-method> ]...
    </web-resource-collection>

    <auth-constraint>
      <role-name>Admin</role-name>
      [ <role-name>Others</role-name> ]...
    </auth-constraint>

    <user-data-constraint>
      <transport-guarantee> NONE | INTEGRAL | CONFIDENTIAL </transport-guarantee>
    </user-data-constraint>
  </security-constraint>

  <!-- authorization path to define role -->
  <security-role><role-name>Admin</role-name></security-role>
  [ <security-role><role-name>Admin</role-name></security-role> ]...

  <login-config>
    <auth-method>BASIC | DIGEST | CLIENT-CERT | FORM</auth-method>
    <form-login-config>
    <form-login-page>/loginPage.html</form-login-page>
    <form-error-page>/loginPage.html</form-error-page>
    </form-login-config>
  </login-config>

</web-app>

context-param เป็นค่าที่กำหนดไว้สำหรับทั้ง application
listener เป็นตัวกำหนดว่าใน application ของเรามี listener อะไรบ้าง

Servlet Configuration

session-timeout กำหนดระยะเวลาที่ session inactive กี่นาที ก่อนจะหลุด session จากตัวอย่างข้างบน คือ ถ้า session inactive 10 นาที ก็จะหลุด ถ้าใส่ 0 หมายถึงให้ time out ทันมี (เสมือนเรียก HttpSession invalidate())
servlet-name ใน servlet เป็นชื่อที่ใช้ใน DD เพื่อเชื่อกับ servlet-name ใน servlet-mappping
servlet-class เป็น Servlet class ที่เราเขียนขึ้นมาเพื่อให้มัน process อะไรสักอย่างสำหรับเวปเรา
jsp-file เป็นชื่อไฟล์ jsp ที่เราต้องการใส่แทน servlet class โดยปกติ jsp สามารถแสดงผลได้โดยไม่ต้องใ่ส่ใน deployment descriptor ก็ได้ แต่เราจะใส่ในกรณีที่เราต้องการ config เพิ่มเติม เช่นต้องการกำหนดค่า init-param แต่ในกรณีที่เราเขียน jsp-file tag แล้ว จะต้องไ่ม่มี servlet-class tag อีก
load-on-startup เป็นการบอกว่าจะให้ servlet นั้นๆ ทำการ load ตั้งแต่ตอน deploy หรือไม่ (เพื่อเป็นการย่นระยะเวลาในการเรียกใช้ของผู้ใช้ในครั้งแรก)

init-param เป็นค่าที่กำหนดไว้สำหรับ servlet นั้นๆ ซึ่งสามารถมี init-param tag ได้มากกว่า 1 ตัวสำหรับหลายๆ parameter

servlet-mapping กำหนดค่ารูปแบบ url ที่จะใช้เรียก servlet ซึ่งลำดับในการ map จะใช้เป็น exact match (คือจะต้องถูกต้องตรงกับ url-pattern ทั้งหมด), directory match (เช่น url-pattern เป็น /test/*) สุดท้ายคือ extension match (เช่น *.do)
url-pattern เป็น URL pattern สำหรับ คนภายนอกที่จะเรียกใช้ ทั้งนี้เราสามารถเขียนเป็น pattern ซึ่งทุก URL ที่ตรงกับ pattern ที่กำหนดจะใช้ Servlet class ตัวเดียวกัน

JSP Configuration

el-ignored กำหนดให้ EL ทำงานหรือไม่ ถ้าเป็น true คือไ่ม่ให้ทำงาน
scripting-invalid กำหนดให้ JSP สามารถใส่ scriptlet ได้หรือไม่

taglib เป็นการกำหนด location ของ Tag Library Descriptor ซึ่งใช้สำหรับก่อน JSP 2.0 ซึ่งจำเป็นต้องบอก location ที่ให้กับ web container แต่ตั้งแต่ JSP 2.0 เป็นต้นไป ไม่จำเป็นต้องมากำหนดใน DD แล้ว web container สามารถหาได้จากการ map ไฟล์ .tld ทุกไฟล์ที่อยู่ใน WEB-INF รวมถึง META-INF ใน jar ไฟล์ แต่ถ้ามีการกำหนดค่าไว้ใน DD และถึงแม้จะเป็น JSP 2.0 web container ก็จะใช้ตัวที่กำหนดไว้ใน DD เท่านั้น

Filter Configuration

Web container จะเรียง filter ตามลำดับที่ปรากฎใน Deployment descriptor โดยจะเลือกที่ map โดย url-pattern ก่อน servlet-name

Error Configuration
exception-type เป็น Class ที่ต้องการจะดักเพื่อให้ redirect ไปยัง error page
error-code นอกจากจะดักเป็น Exception class แล้ว ก็สามารถดักเป็น status code ได้
location เป็น relative location ของ error page

EJB Configuration

env-entry-type จะต้องเป็น Class เท่านั้น เป็น primitive type ไม่ได้

Security Configuration

ส่วนนี้เป็นแยกเป็นส่วนที่เกี่ยวกับ Authorization และ Authentication ซึ่งจะต้องใช้ร่วมกับ web container แต่ละตัว ซึ่งแต่ละียี่ห้อก็จะแตกต่างกัน เช่น Tomcat ใช้การ config ไว้ที่ไฟล์ conf/tomcat-users.xml

ส่วนที่เกี่ยวกับ Authorization จะเป็นการกำหนดว่า resource ไหน จะถูกจำกัดด้วย role ใด โดยวีธีใดบ้าง

security-constraint เป็นส่วนที่กำหนดว่า resources หรือไฟล์ไหนและ method ไหนบ้างที่จะต้องมี constraint กำหนดไว้ เช่น
url-pattern เป็น resource ที่ถูกกำหนดว่าจะต้องมี constraint ซึ่ง กำหนดเป็นไฟล์ใดไฟล์หนึ่ง หรือว่ากำหนดเป็น path ก็ได้ (ในกรณีนี้จะเป็น /path/*) หรือกำหนดเป็น pattern เช่น /path/*.do ก้ได้ แต่อย่างไรก็ตามจะต้องกำหนดอย่างน้อย 1 resouce
auth-contraint เป็นตัวกำหนดว่า resource เหล่านี้จะมี constraint ที่ method ไหนบ้าง ซึ่งจะใช้ได้กับทั้ง resource ใน web-resource-collection

ส่วนถัดมาเป็น Authentication เป็นส่วนกำหนดว่าจะมี role ในบ้าน โดยวีธีการ authentication แบบใด
security-role และ role-name เป็นตัวกำหนดว่าจะมี role อะไรบ้าง

สำหรับโครงสร้างในการ deploy web application จะเป็นดังนี้

Reference:

web.xml Deployment Descriptor for WebLogic Server