cioroianu tagfile

8/14/2019 cioroianu tagfile

1/20

J2EE & Web Services

Creating JSP 2.0 Tag Filesby Andrei Cioroianu

Learn how to build reusable Web templates and database scripts using JSP, JSTL, and SQL

Download the source code for this article

Tag files are one of the most important new additions to JavaServer Pages (JSP) technology, allowingWeb developers to build libraries of custom tags with the JSP syntax. The JSP tag files are translatedinto Java code automatically by the JSP container through the same process that transparently producesJava Servlets from JSP pages. We could say that tag files hide the complexity of building custom JSPtag libraries. While such libraries can be reused across Web applications, they offer significant benefitseven when designed for a specific application because custom tags improve the maintainability of theWeb pages. After reading this article, you'll know how to create and use tag files and how to transformexisting page fragments into tag files.

JSP 2.0 has defined three new directives (, , and ) andtwo new standard actions ( and ) that can be used only in tag files. We'll usethem throughout the article, and you'll find out how to take advantage of the more-advanced tag filefeatures such as "dynamic attributes," "fragment attributes," and "variables named from attributes." Tagfiles can be a powerful tool when used together with the JSP Standard Tag Library (JSTL), whichintroduced the expression language adopted by JSP 2.0 and many JSP actions, including a set of SQLtags. We'll use JSTL and the advanced JSP features to build tag files that update and query a database.

Tag Files Overview

JSP 1.x allows Web developers to build Java components (called tag handlers) that are invoked fromJSP pages via custom tags. Tag handlers are like the old Java Servlets because you use lots of println()calls to generate HTML content and then you have to compile your Java code. The tag files of JSP 2.0are like the JSP pages, because you use the JSP syntax and then the JSP container takes your JSP tagfiles, parses them, generates Java tag handlers, and compiles them automatically. Tag files are invokedfrom JSP pages using custom tags matching the pattern.

In order to be recognized by the JSP container, tag files must be named using the .tag file extension andthey must be placed in the /WEB-INF/tags directory of your Web application or in a subdirectoryof /WEB-INF/tags. If you adopt this deployment method, you don't have to create any Tag LibraryDescriptor (TLD) as you in the case of the JSP libraries implemented with Java tag handlers. You may

also place your tag files in the /META-INF/tags directory of a .jar file, which can be deployed easier,but in this case you have to create a TLD and you have to repack your tag files after every change.

Tag files and JSP pages use almost the same syntax. The first difference you'll notice is the new directive, which is the equivalent of . These two directives have similarattributes, but the former was designed for tag files while the latter can be used only in JSP pages.Instead of declaring their attributes and variables in a separate .tld file, tag files use the and directives. When a tag file is invoked from a JSP page, the custom tag mayhave a body (between and ) that can be executed by thetag file with the action. You'll see how this works in the next section.

Using Tag Files Instead of Page Fragments

In order to have maintainable Web pages, many well-designed JSP 1.x applications use page fragmentsthat are included with or in larger pages, which isn't the ideal methodfor reusing JSP fragments in Web applications. Unlike the page-inclusion solution, tag files have been

Page 1 of 20Creating JSP 2.0 Tag Files

13/08/2008http://www.oracle.com/technology/pub/articles/cioroianu_tagfiles.html?_template=/o ...


2/20

specifically designed for building libraries of reusable page fragments. This section compares thesyntax of the old-fashioned JSP 1.x method with the much better syntax of the JSP 2.0 tag files.

Transforming included pages into tag files. Let's say you have a page named container.jsp that includesanother page named part.jsp with . Execute the following steps totransform part.jsp into a tag file.

Step 1: Move the included page.In the WEB-INF directory of your application, create a subdirectory named tags and move the part.jsppage into WEB-INF/tags.

Step 2: Rename the included page.Because the standard tag file extension is .tag , you have to rename part.jsp to part.tag.

Step 3: Edit the tag file.Open the part.tag file for editing and replace the directive with a similar directive. If you get any compilation errors, some other minor changes might be necessary. UsejspContext instead of pageContext .

Step 4: Declare the tag library.Insert at the beginning of container.jsp.

Step 5: Invoke the tag file.Replace with in container.jsp.

container.jsp (before transformation)

Container Page

container.jsp (after transformation)

Container Page

part.jsp (before transformation)

Included Page

part.tag (after transformation)

Invoked tag

Example based on and . The main page of this example (main.jsp)includes two page fragments (header.jspf and footer.jspf) using the directive. Themain page also includes another page (content.jsp) using . The main.jsp page provides




3/20

three parameters (a, b, and c) to the included page with the help of the standard action.The included content.jsp page outputs the values of the three parameters with ${param.a}, ${param.b},and ${param.c}.

main.jsp

header.jspf

Header

footer.jspf

Footer

content.jsp

Included Content

Parameters - ${param.a}, ${param.b}, ${param.c}

Output

Example based on tag files. The JSP page of this example (main.jsp) uses the directiveto declare the library that contains a tag file (wrapper.tag), indicating its prefix (tags) and the directorywhere the tag file was created (/WEB-INF/tags). The main.jsp page invokes the wrapper.tag file using

the custom tag, which has three attributes (a, b, and c) and some body content (

Wrapped Content
). Note that you may not use any scripting elements between and in the JSP page. Scripting elements include JSP 1.x declarations (), JSP1.x expressions (), and scriptlets (), which are all supported by JSP 2.0. Note that tag



4/20


5/20

Tag files versus and . Custom tags invoking tag files have a morecompact syntax than the combination of and . Custom tags can also benested and indented in a natural way, making the code easy to read. The only thing that might beperceived as a disadvantage is the restriction that doesn't allow you to use scripting elements in thebody of a custom tag that invokes a tag file. This might actually be a plus, considering that scriptlessWeb pages can be maintained more easily. If you have to mix JSP and Java code, you can move theJava scriptlets into the tag file.

More tag file benefits are offered by the , , and directives:

Attribute declarations make the code of the tag file more readable because you can find out thenames of the attributes by just looking at the tag file's header. In the case of the included pages,parameters are not declared at the beginning of the page. If you have to use a page developed bysomeone else and parameters aren't documented, you might have to analyze the source code of the entire page.

By default, all attributes are optional. If an attribute is required, you should specify this with . By default, a custom tag invoking a tag file maycontain scriptless JSP code. If the tag file doesn't use , you should specify that thetag file ignores the body content with . This declarationprevents the accidental use of JSP content between and. In this case, the tag file should be invoked with an empty tag like. By indicating the required attributes and whether the body content isused or not, you can prevent many frequent errors, reducing the time you spend debugging JSPpages. Support for such declarations is not provided for the included JSP pages.

You may also specify the type of an attribute using something like . The value of the attribute will be converted to the specified type

automatically, and an error occurs if the conversion fails. In the case of an included page, allparameters are strings and you must code any necessary conversion.

The new directive provides hints to the JSP container that automates tasks suchas the export and synchronization of the JSP variables, which helps the communication betweenthe invoked tag file and the invoking page. We'll see how this works later in this article. In thecase of the included JSP pages, the interpage communication must be implemented manually,which usually requires more coding.

The and directives enable features that are not available inincluded JSP pages, such as dynamic attributes collected in a java.util.Map, attributes thatrepresent JSP fragments, and variables whose names are specified by attributes. The examples of

the next section use these features.

Using the Advanced JSP 2.0 Features

The following examples show how to exploit the true power of the JSP tag files. You'll learn how tohandle dynamic attributes, how to use variables as output parameters, how to use attributes to namevariables, and how to pass JSP fragments to a tag file using attributes. Then, we'll use these advancedJSP features to build another set of tag files that query and update a database using the JSP expressionlanguage within SQL statements.

Handling dynamic attributes in tag files. This example contains a tag file (dynamicAttr.tag) that acceptsdynamic attributes in addition to several other attributes (listTag, itemTag, and separator) declared withthe directive. A JSP page (dynamicAttr.jsp) invokes the tag file using the tag. Declared and dynamic attributes can be mixed because the order of theattributes doesn't matter.




6/20

By default, a tag file accepts only declared attributes. In order to enable the support for dynamicattributes, the tag file must use , providing the name of avariable that will hold all dynamic attributes in a java.util.Map. In our example, this variable wasnamed attrMap . The dynamicAttr.tag file iterates over the items of attrMap with the action of JSTL, getting the name and value of each attribute with ${attr.key} and ${attr.value}.

If you look at the output, you'll observe that the six dynamic attributes ( first, second, ... sixth )are not obtained in the order specified by the tag in dynamicAttr.jsp. Thishappens because the java.util.Map implementation controls the order of its items. Therefore, tag filesmust be prepared to handle their dynamic attributes in an arbitrary order.

The dynamicAttr.tag file uses the standard action in order to generate HTML elementswhose names are obtained at runtime. This new JSP 2.0 feature is not related to dynamic attributes, butwe use it in this example to generate an HTML list ( listTag is "ul" and itemTag is "li").

dynamicAttr.tag

Dynamic Attributes:

${attr.key} ${separator} ${attr.value}

dynamicAttr.jsp

Output




7/20

Exporting variables from a tag file to a JSP page. The tag of JSTL allows you to create andmodify variables in any of the four JSP scopes (page, request, session, and application). A JSP pageshares the request, session, and application scopes with the tag files that are invoked from the JSP page.The page scope, which is the default scope of , is not shared. Therefore, you may view thevariables created in the request, session, and application scopes as "global variables," while thosecreated in the page scope act as "local variables."

Because each tag file has its own page scope, the local variables of the invoking page are not accessiblein the invoked tag file and vice versa. The JSP page may use tag attributes and global variables to passparameters to the invoked tag. For each attribute, the JSP container creates a local variable in the pagescope of the tag file, which allows you to get the attribute's value using ${attributeName} constructs.Therefore, tag attributes act as parameters passed by value, while global variables act as parameterspassed by reference. If the tag file modifies the value of a global variable, the change affects the JSPpage.

A tag file may "export" its local variables to the invoking page using the directive.The name of a variable can be specified in the tag file using , or theJSP page can provide the variable's name, as we'll see in the varAttr.jsp example. The type of thevariable can be indicated with .

After declaring a variable in a tag file with , you have to set its value with .The JSP container creates another variable with the given name in the JSP page, and this secondvariable is initialized with the value of the corresponding variable from the tag file. Changing the valueof the variable from the JSP page does not affect the corresponding variable from the tag file. The JSPcontainer, however, updates the variable from the JSP page depending on the scope attribute from , which can be AT_BEGIN, NESTED, or AT_END.

If scope is AT_END, the variable from the JSP page is initialized with the value of the tag file variableafter the execution of the tag file. If scope is AT_BEGIN, the variable from the JSP page is updatedbefore , before each , and at the end of the tag file's execution. If scope isNESTED, the JSP variable is updated only before and before each with thevalue of the tag file variable. After the execution of the tag file, in the NESTED case, the JSP variable

is restored to the value it had before the invocation of the tag file.For a better understanding of how variables work, let's use them in an example that is made of a tag file(varScope.tag), a JSP page (varScope.jsp), and several fragments (varScopeRow.tagf,




8/20

varScopeHeader.jspf, varScopeFooter.jspf, and varScopeRow.jspf). The fragments are used only tocreate an HTML table. We have to use in this example to separate the logic from thepresentation while studying the tag file variables. Using tag files for presentation is the best solution inmost situations, but in this case the additional tag files would interfere with the variable "exporting"mechanisms that we want to study.

The tag file uses a "global" variable (GV), an undeclared "local" variable ( LV ), and three variables ( BV,NV, and EV) declared with . The varScope.tag file initializes these variables with "TAGA", then it uses , and finally it changes the values of all variables to the "TAG B" string.The varScope.jsp page initializes its own set of variables with "JSP A" and then invokes the tag filewith , changing the values of the variables to "JSP B" within the body of . The resulting output is included after the source code.

varScope.tag

varScopeRow.tagf

${tagPhase}

${LV != null ? LV : "null"}

${GV != null ? GV : "null"}





9/20


10/20

NV
Tag Var
Scope:
NESTED

EV
Tag Var
Scope:
AT_END

varScopeFooter.jspf

varScopeRow.jspf

${jspPhase}


${GV != null ? GV : "null"}


${BV != null ? BV : "null"}

${NV != null ? NV : "null"}

${EV != null ? EV : "null"}

Output




11/20

Using attributes to provide names for variables. The previous example showed how to use variableswhose names are given by the tag file. The following example has a tag file (varAttr.tag) that creates avariable whose name is provided by a JSP page (varAttr.jsp) as the value of a tag attribute ( v ). In orderto be able to operate with the variable, the tag file defines an alias ( a ) using .

The varAttr.tag file sets the value of the variable with , outputs thevariable's name with ${v}, and outputs the variable's value with ${a}. The varAttr.jsp page invokes thetag file with and works with the variable named x . Note that the JSP containercreates the x variable automatically, setting it to the value of a, which is 123 .

varAttr.tag

TAG: ${v} = ${a}

varAttr.jsp

JSP: x = ${x}




12/20

Output

Invoking JSP fragments from tag files. You've learned so far that tag files support two attribute types:simple declared attributes and dynamic attributes. There is a third type called fragment attributes. TheJSP page of this example (fragmentAttr.jsp) invokes a tag file (fragmentAttr.tag) with, providing two simple attributes ( attr1 and attr2 ) and a fragment attribute(template ). All three attributes are declared in the tag file with , but only template is declared as a fragment attribute with fragment="true" .

The fragmentAttr.jsp page uses the and standard actions to define the twoJSP fragments that are invoked from the tag file with and , respectively. Inaddition, the tag file declares a nested variable ( data ) with . The value of the variableis set by the tag file with , and the two JSP fragments output the variable's value with ${data}.

fragmentAttr.tag

fragmentAttr.jsp

Template: ${data}

Body Content: ${data}




13/20

Output

Using Tag Files to Update and Query Databases

When developing complex enterprise applications, many prefer to use the Enterprise JavaBeans (EJB)technology, letting the application server manage the object persistence. Others might prefer to use theJava Database Connectivity (JDBC) standard API in order to optimize the database access manually.

These solutions might not be suitable in the case of a simple database-backed Web site that just needsto be prototyped as fast as possible using JSPs. A tag library providing database access features can bethe best solution if you just need to query and update a simple database.

JSTL has a set of simple SQL tags that we'll use in the following examples. Instead of invoking theJSTL SQL tags directly from your pages, it's a good idea to separate the presentation from the databaseaccess scripts using tag files. This separation allows you to switch easily to another databaseconnectivity solution, at a later time, in order to increase the performance and scalability of yourapplication.

JSTL is not the only tag library providing database access features. Oracle Application DevelopmentFramework (ADF) offers a JSP library called Business Components Data Tags that contains a more

advanced set of database-related JSP tags. Note that the set of ADF features is much broader, makingOracle ADF suitable for simple and complex applications. Oracle ADF is bundled together withJDeveloper 10 g , which has visual design tools for ADF.

The following six examples create a table, insert three rows, update a row, delete another row, performa couple of queries, and drop the table. Everything is done with generic tag files that don't depend onthe table's structure.

Step 1: Create table. The JSP page of this example (create.jsp) invokes a tag file (create.tag) to create atable whose structure is provided as the body of the custom tag. The table attributespecifies the name of the table ( People ). After creating the table, the JSP page outputs a messagenotifying the user that the operation was completed:

userID INTEGER,name VARCHAR2(60),




14/20

email VARCHAR2(60)

Table created.

The create.tag file includes a tag fragment (init.tagf) that sets a javax.sql.DataSource variable namedtags_db_dataSource within the application scope with the help of the tag of JSTL. The variable is created only if it doesn't already exist and is used in the tag file with the tag of JSTL, which executes the SQL statement from its body. The create.tag file buildsthe CREATE TABLE statement dynamically, getting the table's name with ${table} and inserting thetable's structure with :

CREATE TABLE ${table} ( )

In order to run the examples, you'll have to configure a datasource named dbtags. A reference to thisresource is declared in the Web application's descriptor (web.xml):

jdbc/dbtagsjavax.sql.DataSourceContainer

The init.tagf fragment gets the path to the resource from an initialization parameter that is defined inweb.xml too:

tags_db_dataSourcejdbc/dbtags

If you want to use another datasource, you just have to replace dbtags with the name of yourdatasource in the web.xml file.

init.tagf

create.tag

CREATE TABLE ${table} ( )

create.jsp




15/20

userID INTEGER,name VARCHAR2(60),email VARCHAR2(60)

Table created.

Step 2: Insert. Once you have a table, you can insert one row at a time using the tag, whichinvokes a tag file (insert.tag) with the following syntax:

An example JSP page (insert.jsp) uses to insert three rows into the People table. At eachinvocation, the tag file builds and executes an SQL statement using the following syntax:

INSERT INTO table (column1, column2, ...) VALUES ( value1, value2 , ...)

The column names and values are specified as dynamic attributes so that can be used with

any table, no matter how its columns are named. The tag file uses to iterate over theentries of a java.util.Map instance ( columnAttr ) holding the dynamic attributes of . Thename of each dynamic attribute represents a column name and is obtained with ${v_entry.key}. The tagfile gets the values that must be inserted into the table with ${v_entry.value}.

Within the body of , the tag file builds a list of column names ( v_columnNames ) andanother list containing parameter markers ( v_paramMarkers ). The tag of JSTL cooperateswith transmitting the values of the SQL parameters. After the loop, whichproduces no output, the tag file generates the SQL statement with

INSERT INTO ${table} (${v_columnNames}) VALUES (${v_paramMarkers})

When the tag file is invoked by insert.jsp, the tag evaluates its body obtainingINSERT INTO People (userID, name, email) VALUES (?, ?, ?)

Then, executes the above SQL statement using the JDBC API and passing the parametervalues that were transmitted by . Note that the columns and their corresponding valuesmay appear in a different order because they are retrieved from a java.util.Map instance. Therefore, wehave to make sure that the SQL statement does not rely on the order of the columns.

insert.tag

INSERT INTO ${table} (${v_columnNames})

VALUES (${v_paramMarkers})




16/20

insert.jsp

Rows inserted.

Step 3: Update. The update.jsp page uses to change the email value of one of the rowsinserted with insert.jsp. The update.tag file is similar to insert.tag, but this time the tag of JSTL is used to execute an UPDATE statement:

UPDATE table SET column1=value1, column2=value2 , ... WHERE ...

The columns and their values are specified as dynamic attributes using the following syntax:

The tag file uses the dynamic attributes to build a list ( v_setList ) containing column=? constructs.The column values are transmitted to with the help of as in the previousexample. Then, update.tag generates the SQL statements with

UPDATE ${table} SET ${v_setList} WHERE ${where}

When the tag file is invoked by update.jsp, the tag evaluates its body obtaining

UPDATE People SET email=? WHERE userID=2

Unlike the tag that may be used to insert only one row at a time, the tag can beused to update multiple rows with a single invocation.

update.tag

UPDATE ${table} SET ${v_setList} WHERE ${where}

update.jsp

Resources

Use the following resourcesto test the examples andlearn more about the JSP2.0 tag files and about theJSTL Core and SQL tags.

Download the Source CodeThe tagfiles_src.zip filecontains the examples of this article. In order to runthem, you need J2SE, a

J2EE 1.4 application server,JSTL 1.1, and a databaseserver.




17/20

Row updated.

Step 4: Delete. The following tag file (delete.tag) can be used to deleteone or more rows, as in the delete.jsp page.

delete.tag

DELETE FROM ${table} WHERE ${where}

delete.jsp

Row deleted.

Step 5: Select. The next tag file (select.tag) uses the tag of JSTL to execute SELECT statements. The syntax of isincluded below:

process the result of the query, one row at a time

The tag builds and executes the following SQL statement,whose clauses are specified as the attributes of the tag.

SELECT columns FROM table WHERE ...GROUP BY ... HAVING ... ORDER BY ...

When appears in a JSP page, its body is invoked for eachrow with the action form select.tag. The JSP page getsthe row data from a java.util.Map created by the tag file with JSTL. Forexample, the values of the current row can be obtained with JSPconstructs like ${row.userID}, ${row.name}, and ${row.email},assuming that the JSP page invokes the tag file specifying that thevariable holding the data should be named row :

${row.userID} ... ${row.name} ... ${row.email}

The select.jsp page invokes the tag file twice. First it uses to iterate over the relational table's rows generating an HTML table, and

Download OC4J 10 g Oracle Application ServerContainers for J2EE 10gfully implement the J2EE1.4 specs, which includeJSP 2.0. You may use OC4J10g (10.0.3) to test theexamples. It works with allmajor database servers,includingof courseOracle Database.

Download JSTL 1.1Before deploying theexamples, download JSTLand copy jstl.jar andstandard.jar into the WEB-INF/lib directory of theWeb application. Also,don't forget to configure thedbtags datasource and makesure that the properdatabase driver is available.

Read the JSP 2.0SpecificationThe JSP 2.0 specificationhas an entire chapterdedicated to tag files ("PartI: Chapter JSP.8 TagFiles"). The new standardactions introduced by JSP2.0 are described in anotherchapter ("Part I: ChapterJSP.5 Standard Actions").

Read the JSTL 1.1SpecificationThe JSTL specificationdescribes the ,, ,,, ,and tags usedin the examples of thisarticle.

Related Articles andDownloads

How-To: Add a CustomJSP Tag Library toJDeveloper 10 g

Oracle JDeveloper 10 g




18/20

then the JSP page uses to count the rows of the People table.

select.tag

SELECT ${empty columns ? "*" : columns} FROM ${table} WHERE ${where} GROUP BY ${groupBy} HAVING ${having} ORDER BY ${orderBy}

select.jsp

User ID Name Email

${row.userID} ${row.name} ${row.email}

${c.n} people.

Output

JSP Sample Code

Tutorial: Understanding theNew Features of JSP 2.0,"Tag Files" module




19/20

Step 6: Drop table. If you want to execute again the JSP examples, you have to drop the table with thedrop.jsp page that uses the drop.tag file.

drop.tag

DROP TABLE ${table}

drop.jsp

Table dropped.

Conclusion

Tag files are the easy-to-use solution that Web developers need in order to build custom tag libraries.The transition from Java tag handlers to JSP tag files is similar to the transition from Servlets to JSPthat happened several years ago. When developing Java Web applications, most of the dynamic contentis now generated with JSP, but Servlets are still used as an underlying technology for JSPs and thereare cases when Servlets are preferred instead of JSP. Similarly, Java tag handlers are still needed as anunderlying technology for tag files and for building sophisticated tag libraries such as JSTL. Most taglibraries, however, will be built using tag files because they simplify the development process.

Andrei Cioroianu ([email protected] ) is the founder of Devsphere (www.devsphere.com ), aprovider of Java frameworks, XML consulting, and Web development services. Andrei Cioroianu haswritten many Java articles published by ONJava, JavaWorld, and Java Developer's Journal. He also

coauthored the books Java XML Programmer's Reference and Professional Java XML (both fromWrox Press).




20/20

Please rate this document:

Excellent Good Average Below Average Poor

Send us your comments

Rate and View Results


cioroianu tagfile

Documents

Transcript of cioroianu tagfile