[SCWCD 5] API and Syntactical Reference

Mohammad Albaba msualbaba@gmail.com

Acknowledgements:
I would like to thank the following people: Charles Lyons for his book SCWCD Study Companion. Franck Allimant for his Java Documentation in HTMLHelp format. Frederic Esnault for his inspiring notes.

* This reference was ordered based on Charles Lyons book.

Contents
Chapter 3: Servlet Basics ..................................................................................................................................................... 3 Chapter 4: Servlet Contexts ................................................................................................................................................ 4 Chapter 5: Requests and Responses ................................................................................................................................... 6 Chapter 6: Request Dispatching and Wrappers ................................................................................................................ 11 Chapter 7: Filters .............................................................................................................................................................. 13 Chapter 8: Session Management ...................................................................................................................................... 14 Chapter 10: JSP basics ....................................................................................................................................................... 16 Chapter 15: Custom Tags .................................................................................................................................................. 18 Chapter 11: JSP Documents .............................................................................................................................................. 21 Chapter 12: EL ................................................................................................................................................................... 21 Chapter 13: Standard Actions and JavaBeans................................................................................................................... 21 Chapter 14: Tag libraries and JSTL .................................................................................................................................... 22 Chapter 16: Tag files ......................................................................................................................................................... 23 Chapter 9: Application Deployment ................................................................................................................................. 24 Chapter 18: Security.......................................................................................................................................................... 26 Chapter 17: Tag Deployment ............................................................................................................................................ 27 Chapter 20: Servlets 2.5 and JSP 2.1 Changes .................................................................................................................. 29

Chapter 3: Servlet Basics

All servlets implement the interface: javax.servlet.Servlet
GenericServlet implements Servlet, ServletConfig HttpServlet extends GenericServlet UnavailableException extends ServletException javax.servlet.ServletException javax.servlet.UnavailableException

javax.servlet.Servlet public void init(ServletConfig config) throws ServletException public void service(ServletRequest req,ServletResponse res) throws ServletException, IOException public void destroy()

javax.servlet.GenericServlet public void init(ServletConfig config) throws ServletException public void init() throws ServletException public abstract void service(ServletRequest req, ServletResponse res) throws ServletException, IOException

javax.servlet.http.HttpServlet protected void service(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException public void service(ServletRequest req, ServletResponse res) throws ServletException, IOException

Chapter 4: Servlet Contexts

javax.servlet.ServletContext public Object getAttribute(String name) public Enumeration getAttributeNames() public void setAttribute(String name, Object object) public void removeAttribute(String name) public String getServletContextName() public String getRealPath(String path) public Set getResourcePaths(String path) public ServletContext getContext(String uripath) public URL getResource(String path) throws MalformedURLException public InputStream getResourceAsStream(String path) public String getMimeType(String file) public RequestDispatcher getRequestDispatcher(String path) public RequestDispatcher getNamedDispatcher(String name) public String getInitParameter(String name) public Enumeration getInitParameterNames()

javax.servlet.ServletConfig public ServletContext getServletContext() public String getInitParameter(String name) public Enumeration getInitParameterNames() public String getServletName()

javax.servlet.GenericServlet public ServletConfig getServletConfig() public ServletContext getServletContext() public String getInitParameter(String name) public Enumeration getInitParameterNames() public String getServletName()

javax.servlet.ServletContextListener public void contextInitialized(ServletContextEvent sce) public void contextDestroyed(ServletContextEvent sce)

javax.servlet.ServletContextEvent public ServletContext getServletContext()

javax.servlet.ServletContextAttributeListener public void attributeAdded(ServletContextAttributeEvent scab) public void attributeRemoved(ServletContextAttributeEvent scab) public void attributeReplaced(ServletContextAttributeEvent scab)

javax.servlet.ServletContextAttributeEvent public String getName() public Object getValue()

Chapter 5: Requests and Responses

HttpServletRequest extends ServletRequest HttpServletResponse extends ServletResponse

javax.servlet.ServletRequest public Object getAttribute(String name) public Enumeration getAttributeNames() public void removeAttribute(String name) public void setAttribute(String name, Object o) public String getParameter(String name) public String[] getParameterValues(String name) public Enumeration getParameterNames() public Map getParameterMap() public ServletInputStream getInputStream() throws IOException Throws: IllegalStateException - if the getReader() method has already been called for this request IOException - if an input or output exception occurred public BufferedReader getReader() throws IOException Throws: IllegalStateException - if getInputStream() method has been called on this request IOException - if an input or output exception occurred public RequestDispatcher getRequestDispatcher(String path)

javax.servlet.http.HttpServletRequest public Enumeration getHeaders(String name) public String getHeader(String name) public Enumeration getHeaderNames() public int getIntHeader(String name) Throws: (unchecked) NumberFormatException - If the header value can't be converted to an int public long getDateHeader(String name) Throws: (unchecked) IllegalArgumentException - If the header value can't be converted to a date

public String getAuthType() public String getRemoteUser() public java.security.Principal getUserPrincipal() public boolean isUserInRole(String role) public javax.servlet.http.Cookie [] getCookies() public String getRequestedSessionId() public HttpSession getSession() public HttpSession getSession(boolean create) public boolean isRequestedSessionIdValid() public boolean isRequestedSessionIdFromCookie() public boolean isRequestedSessionIdFromURL()

javax.servlet.ServletResponse public ServletOutputStream getOutputStream() throws IOException Throws: IllegalStateException - if the getWriter method has been called on this response IOException - if an input or output exception occurred public PrintWriter getWriter() throws IOException Throws: UnsupportedEncodingException - if the character encoding returned by getCharacterEncoding cannot be used IllegalStateException - if the getOutputStream method has already been called for this response object IOException - if an input or output exception occurred public void flushBuffer() throws IOException public int getBufferSize() public boolean isCommitted() public void reset() Throws: IllegalStateException - if the response has already been committed public void resetBuffer() Throws: IllegalStateException - if the response has already been committed public void setBufferSize(int size) Throws: IllegalStateException - if this method is called after content has been written

public void setCharacterEncoding(String charset) public String getCharacterEncoding() public String getContentType() public void setContentType(String type) public Locale getLocale() public void setLocale(Locale loc) public void setContentLength(int len)

javax.servlet.http.HttpServletResponse public void addHeader(String name, String value) public void setHeader(String name, String value) public boolean containsHeader(String name) public void addIntHeader(String name, int value) public void setIntHeader(String name, int value) public void addDateHeader(String name, long date) public void setDateHeader(String name, long date) public void setStatus(int sc) public void sendError(int sc) throws IOException

Throws: IOException - If an input or output exception occurs IllegalStateException - If the response was committed before this method call public void sendError(int sc, String msg) throws IOException Throws: IOException - If an input or output exception occurs IllegalStateException - If the response was committed public void sendRedirect(String location) throws IOException Throws: IOException - If an input or output exception occurs IllegalStateException - If the response was committed or if a partial URL is given and cannot be converted into a valid URL public String encodeURL(String url) public String encodeRedirectURL(String url) public void addCookie(Cookie cookie)

javax.servlet.ServletRequestListener public void requestInitialized(ServletRequestEvent sre) public void requestDestroyed(ServletRequestEvent sre)

javax.servlet.ServletRequestEvent public ServletRequest getServletRequest() public ServletContext getServletContext()

javax.servlet.ServletRequestAttributeListener public void attributeAdded(ServletRequestAttributeEvent srae) public void attributeRemoved(ServletRequestAttributeEvent srae) public void attributeReplaced(ServletRequestAttributeEvent srae)

javax.servlet.ServletRequestAttributeEvent public String getName() public Object getValue()

javax.servlet.http.Cookie public Cookie(String name, String value) Throws: IllegalArgumentException - if the cookie name contains illegal characters (for example, a comma, space, or semicolon) or it is one of the tokens reserved for use by the cookie protocol public void setComment(String purpose) public String getComment() public void setDomain(String pattern) public String getDomain() public void setMaxAge(int expiry) public int getMaxAge() public void setPath(String uri) public String getPath() public void setSecure(boolean flag) public boolean getSecure() public String getName() public void setValue(String newValue) public String getValue() public int getVersion() public void setVersion(int v)

Chapter 6: Request Dispatching and Wrappers

ServletRequestWrapper implements ServletRequest HttpServletRequestWrapper extends ServletRequestWrapper implements HttpServletRequest ServletResponseWrapper implements ServletResponse HttpServletResponseWrapper extends ServletResponseWrapper implements HttpServletResponse javax.servlet.RequestDispatcher public void forward(ServletRequest request, ServletResponse response) throws ServletException, IOException Throws: ServletException - if the target resource throws this exception IOException - if the target resource throws this exception IllegalStateException - if the response was already committed public void include(ServletRequest request, ServletResponse response) throws ServletException, IOException Throws: ServletException - if the included resource throws this exception IOException - if the included resource throws this exception

During include, the following attributes are set on the request:

javax.servlet.include.request_uri javax.servlet.include.context_path javax.servlet.include.servlet_path javax.servlet.include.path_info javax.servlet.include.query_string

These attributes are not set if the requestDispatcher was obtained from getNamedDispatcher method. During forward, the following attributes are set on the request:
javax.servlet.forward.request_uri javax.servlet.forward.context_path javax.servlet.forward.servlet_path javax.servlet.forward.path_info javax.servlet.forward.query_string

These attributes always reflect the original request information, regardless if the container forwards or includes the request any further.

javax.servlet.ServletRequestWrapper public ServletRequestWrapper(ServletRequest request) Throws: IllegalArgumentException - if the request is null public ServletRequest getRequest() public void setRequest(ServletRequest request) Throws: IllegalArgumentException - if the request is null.

javax.servlet.http.HttpServletRequestWrapper public HttpServletRequestWrapper(HttpServletRequest request) Throws: IllegalArgumentException - if the request is null

javax.servlet.ServletResponseWrapper public ServletResponseWrapper(ServletResponse response) Throws: IllegalArgumentException - if the response is null. public ServletResponse getResponse() public void setResponse(ServletResponse response) Throws: IllegalArgumentException - if the response is null.

javax.servlet.http.HttpServletResponseWrapper public HttpServletResponseWrapper(HttpServletResponse response) Throws: IllegalArgumentException - if the response is null

Chapter 7: Filters
javax.servlet.Filter public void init(FilterConfig filterConfig) throws ServletException public void destroy() public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException

javax.servlet.FilterChain public void doFilter(ServletRequest request, ServletResponse response) throws IOException, ServletException

javax.servlet.FilterConfig public String getFilterName() public ServletContext getServletContext() public String getInitParameter(String name) public Enumeration getInitParameterNames()

Chapter 8: Session Management

javax.servlet.http.HttpSession NOTE: All the methods after the first three throw IllegalStateException if called on an invalidated session public int getMaxInactiveInterval() in seconds public void setMaxInactiveInterval(int interval) public ServletContext getServletContext() public Object getAttribute(String name) public Enumeration getAttributeNames() public void setAttribute(String name, Object value) public void removeAttribute(String name) public long getCreationTime() public String getId() public void invalidate() public boolean isNew() public long getLastAccessedTime()

javax.servlet.http.HttpSessionListener public void sessionCreated(HttpSessionEvent se) public void sessionDestroyed(HttpSessionEvent se)

javax.servlet.http.HttpSessionActivationListener public void sessionDidActivate(HttpSessionEvent se) public void sessionWillPassivate(HttpSessionEvent se)

javax.servlet.http.HttpSessionEvent public HttpSession getSession()

javax.servlet.http.HttpSessionAttributeListener public void attributeAdded(HttpSessionBindingEvent se) public void attributeRemoved(HttpSessionBindingEvent se) public void attributeReplaced(HttpSessionBindingEvent se)

javax.servlet.http.HttpSessionBindingListener public void valueBound(HttpSessionBindingEvent event) public void valueUnbound(HttpSessionBindingEvent event)

javax.servlet.http.HttpSessionBindingEvent public String getName() public Object getValue()

Chapter 10: JSP basics

PageContext extends JspContext javax.servlet.jsp.JspContext public abstract Object findAttribute(String name) public abstract void setAttribute(String name, Object value) public abstract void setAttribute(String name, Object value, int scope) public abstract Object getAttribute(String name, int scope) public abstract Object getAttribute(String name) public abstract void removeAttribute(String name) public abstract void removeAttribute(String name, int scope) public abstract int getAttributesScope(String name) public abstract Enumeration getAttributeNamesInScope(int scope) public abstract JspWriter getOut() public abstract ExpressionEvaluator getExpressionEvaluator() public abstract VariableResolver getVariableResolver() public JspWriter pushBody(Writer writer) public JspWriter popBody()

javax.servlet.jsp.PageContext public abstract Exception getException() public abstract Object getPage() public abstract ServletRequest getRequest() public abstract ServletResponse getResponse() public abstract ServletConfig getServletConfig() public abstract ServletContext getServletContext() public abstract HttpSession getSession() public abstract void forward(String relativeUrlPath) throws ServletException, IOException public abstract void include(String relativeUrlPath) throws ServletException, IOException public abstract void include(String relativeUrlPath, boolean flush) throws ServletException, IOException public abstract void handlePageException(Exception e) throws ServletException, IOException public abstract void handlePageException(Throwable t) throws ServletException, IOException public ErrorData getErrorData()

Chapter 15: Custom Tags

All tags must implement the interface: javax.servlet.jsp.tagext.JspTag
Tag extends JspTag IterationTag extends Tag TagSupport implements IterationTag BodyTag extends IterationTag BodyContent extends JspWriter BodyTagSupport extends TagSupport implements BodyTag SimpleTag extends JspTag SimpleTagSupport implements SimpleTag javax.servlet.jsp.tagext.Tag public void setParent(Tag t) public void setPageContext(PageContext pc) public Tag getParent() public void release() public int doStartTag() throws JspException return: Tag.EVAL_BODY_INCLUDE, BodyTag.EVAL_BODY_BUFFERED, SKIP_BODY public int doEndTag() throws JspException return: EVAL_PAGE, SKIP_PAGE

javax.servlet.jsp.tagext.IterationTag public int doAfterBody() throws JspException return: EVAL_BODY_AGAIN, SKIP_BODY

javax.servlet.jsp.tagext.TagSupport The default behavior is: doStartTag() > SKIP_BODY, doAfterBody() > SKIP_BODY, doEndTag() > EVAL_PAGE

javax.servlet.jsp.tagext.BodyTag This interface provides a buffer to which all evaluated body content is written. Both of the following methods will be invoked when doStartTag() returns EVAL_BODY_BUFFERED and the body of the tag is not empty. public void doInitBody() throws JspException

public void setBodyContent(BodyContent b)

javax.servlet.jsp.tagext.BodyContent public void clearBody() public void flush() throws IOException (always thrown) public JspWriter getEnclosingWriter() public abstract Reader getReader() public abstract String getString() public abstract void writeOut(Writer out) throws IOException

javax.servlet.jsp.tagext.BodyTagSupport Default return values: doStartTag() > EVAL_BODY_BUFFERED doAfterBody() > SKIP_BODY doEndTag() > EVAL_PAGE

javax.servlet.jsp.tagext.SimpleTag public void setJspContext(JspContext pc) public void setParent(JspTag parent) public JspTag getParent() public void setJspBody(JspFragment jspBody) public void doTag() throws JspException, IOException

javax.servlet.jsp.tagext.JspFragment public abstract void invoke(Writer out) throws JspException, IOException public abstract JspContext getJspContext() javax.servlet.jsp.tagext.DynamicAttributes

public void setDynamicAttribute(String uri, String localName, Object value) throws JspException

Chapter 11: JSP Documents

JSP Documents <jsp:root xmlns:jsp=url version=2.0> </jsp:root> Or <anything:root xmlns:anything=url version=2.0> </anything:root> <jsp:directive.page /> <jsp:directive.include /> <jsp:directive.tag /> <jsp:declaration></jsp:declaration> <jsp:scriptlet></jsp:scriptlet> <jsp:expression></jsp:expression> <jsp:text></jsp:text>

Chapter 12: EL
EL Functions <taglib> <function> <name></name> <function-class></function-class> <function-signature></function-signature> </function> </taglib>

Chapter 13: Standard Actions and JavaBeans

Standard Actions

<jsp:useBean id scope type

class|beanName />

<jsp:setProperty name property value param> <jsp:getProperty name property /> <jsp:include page flush> <jsp:forward page /> <jsp:param name value >

Chapter 14: Tag libraries and JSTL

JSTL
<c:out value escapeXml default /> <c:catch var> </c:catch> <c:set var value scope /> <c:set target property value/> <c:remove var scope /> <c:if test var scope /> <c:choose> <c:when test></c:when> <c:otherwise><c:otherwise> </c:choose> <c:forEach begin end step var></c:forEach> <c:forEach items></c:forEach> Methods during iterations: Object getCurrent() int getIndex() int getCount() boolean isFirst() boolean isLast() Integer getBegin() Integer getEnd() Integer getStep() <c:forTokens items delims var begin end step varStatus></c:forTokens> <c:url value context var scope />

<c:import url context varReader /> <c:redirect url context /> <c:param name value /> or <c:param name>value</c:param>

Chapter 16: Tag files

Tag Files <%@ tag body-content dynamic-attributes language import pageEncoding isELIgnoerd %> Or <jsp:directive.tag /> <%@ attribute name required fragment rtexprvalue type %> Or <jsp:directive.attribute /> <%@ variable name-given variable-class declare scope name-from-attribute alias %> Or <jsp:directive.variable /> <jsp:doBody var varReader scope/> <jsp:invoke fragment/>

Chapter 9: Application Deployment

The Deployment Descriptor Syntax

All elements are encapsulated inside <web-app> tag. <context-param> <description></description> <param-name></param-name> <param-value></param-value> </context-param> <filter> <description></description> <display-name></display-name> <icon></icon> <filter-name></filter-name> <filter-class></filter-class> <init-param></init-param> </filter> <init-param> <description></description> <param-name></param-name> <param-value></param-value> </init-param> <filter-mapping> <filter-name></filter-name> <url-pattern></url-pattern> or <servlet-name></servlet-name> <dispatcher>FORWARD | INCLUDE | REQUEST | ERROR </dispatcher> </filter-mapping> <listener> <description></description> <display-name></display-name> <icon></icon> <listener-class></listener-class> </listener> <servlet> <description></description> <display-name></display-name> <icon></icon> <servlet-name></servlet-name> <servlet-class></servlet-class> or <jsp-file></jsp-file> <init-param></init-param> <load-on-startup></load-on-startup> <run-as></run-as> <security-role-ref></security-role-ref> </servlet>

<servlet-mapping> <servlet-name></servlet-name> <url-pattern></url-pattern> </servlet-mapping> <session-config> <session-timeout></session-timeout> </session-config> <mime-mapping> <extension></extension> <mime-type></mime-type> </mime-mapping> <welcome-file-list> <welcome-file></welcome-file> </welcome-file-list> <error-page> <error-code></error-code> or <exception-type></exception-type> <location></location> </error-page> When the container forwards to an error page, it sets the following request-scoped attributes: javax.servlet.error.status_code javax.servlet.error.exception_type javax.servlet.error.message javax.servlet.error.exception javax.servlet.error.request_uri javax.servlet.error.servlet_name <jsp-config> <description></description> <display-name></display-name> <icon></icon> <taglib> <taglib-uri></taglib-uri> <taglib-location></taglib-location> </taglib> <jsp-property-group> <description></description> <display-name></display-name> <icon></icon> <url-pattern></url-pattern> <el-ignored></el-ignored> <page-encoding></page-encoding> <scripting-invalid></scripting-invalid> <is-xml></is-xml> <include-prelude></include-prelude> <include-coda></include-coda> </jsp-property-group> </jsp-config>

Chapter 18: Security

The Deployment Descriptor Syntax (Security Configuration)

<login-config> <auth-method>BASIC | DIGEST | CLIENT-CERT</auth-method> <realm-name> (doesnt exist when using client-cert) </realm-name> </login-config> <login-config> <auth-method>FORM</auth-method> <form-login-config> <form-login-page></form-login-page> <form-error-page></form-error-page> </form-login-config> </login-config> <form method=post action=j_security_check> <input type=text name=j_username /> <input type=password name=j_password /> </form> <security-role> <description></description> <role-name></role-name> </security-role> <security-constraint> <display-name></display-name> <web-resource-collection> <web-resource-name></web-resource-name> <description></description> <url-pattern></url-pattern> <http-method></http-method> </web-resource-collection> <auth-constraint> <description></description> <role-name></role-name> </auth-constraint> <user-data-constraint> <description></description> <transport-guarantee>NONE |INTEGRAL | CONFIDENTIAL</transport-guarantee> </user-data-constraint> </security-constraint>

<servlet> <run-as></run-as> <security-role-ref> <description></description><role-name></role-name><role-link></role-link> </security-role-ref> </servlet>

Chapter 17: Tag Deployment

Tag Library Descriptor (TLD) Syntax

<taglib> <description></description> <display-name></display-name> <icon></icon> <tlib-version></tlib-version> <short-name></short-name> <uri></uri> <validator></validator> <listener></listener> <tag></tag> <tag-file></tag-file> <function></function> <taglib-extension></taglib-extension> <taglib> <validator> <description></description> <validator-class></validator-class> <init-param> <description></description> <param-name></param-name> <param-value></param-value> </init-param> </validator> <listener> <description></description> <display-name></display-name> <icon></icon> <listener-class></listener-class> </listener> <tag> <description></description> <display-name></display-name> <icon></icon> <name></name> <tag-class></tag-class> <tei-class></tei-class> <body-content>empty | tagdependent | JSP | scriptless</body-content> <variable></variable> <attribute></attribute> <dynamic-attributes></dynamic-attributes> <example></example> <tag-extension></tag-extension> </tag> <tag-extension> <extension-element></extension-element> </tag-extension>

<variable> <description></description> <name-given></name-given> or <name-from-attribute></name-from-attribute> <variable-class></variable-class> <declare></declare> <scope></scope> </variable> <attribute> <description></description> <name></name> <required></required> <fragment></fragment> or <rtexprvalue></rtexprvalue><type></type> </attribute> <tag-file> <description></description> <display-name></display-name> <icon></icon> <name></name> <path></path> <example></example> <tag-extension></tag-extension> </tag-file> <function> <description></description> <display-name></display-name> <icon></icon> <name></name> <function-class></function-class> <function-signature></function-signature> <example></example> <function-extension> <extension-element></extension-element> </function-extension> </function>

Chapter 20: Servlets 2.5 and JSP 2.1 Changes

Servlets 2.5 Changes

Faces and JSTL are mandatory by default in any JEE-compliant container. Now you can use a filter to intercept only dynamic components and not static ones by using * wildcard: <filter-mapping> <filter-name></filter-name> <servlet-name>*</servlet-name > </ filter-mapping> Its now possible have many patterns inside a servlet mapping: <servlet-mapping> <servlet-name></servlet-name> <url-pattern></url-pattern> <url-pattern></url-pattern> <url-pattern></url-pattern> </servlet-mapping> You can also apply many patterns and servlet names inside a filter mapping: <filter-mapping> <url-pattern></url-pattern> <servlet-name></servlet-name> <url-pattern></url-pattern> <servlet-name></servlet-name> <url-pattern></url-pattern> <servlet-name></servlet-name> </filter-mapping> When no dynamic components exist, you dont need a web.xml A new method getContextPath() has been added to ServletContext. Its the responsibility of a developer to handle synchronization properly on HttpSession and ServletContext: <% synchronized(application) { application.setAttribute(A, A); } synchronized(session) { session.setAttribute(B, B); } %> @DeclareRoles({X, Y, Z}) @RunAs(Admin)

@Resource(name=, type=) This is equivalent to declaring <resource-ref> in the deployment descriptor. @Resources({@Resource(name=, type=), @Resource(name=, type=)}) @PostContruct @PreDestroy @EJB replaces <ejb-ref> and <ejb-local-ref> @WebServiceRef replaces <resource-ref>