Sun Technologies: Java Enterprise Edition

SUN TECHNOLOGIES: JAVA ENTERPRISE EDITION
17/10/09 18:17
Introduction
Do you need to set up distributed applications? Which more is, with a simple, powerful, and easily maintainable architecture? EJB will certainly answer your waiting. Moreover, behind this name, there are several technologies: one allowing managing the conversation on the network, another to supervise the data base... and well of others still. The common point between them is that you externalize on an application server logic trade of an application. Thus, as this part treated, you will have to write the "frontal" part of your application (see ?architecture Java EE?).
To help you to conceptualize this technology, we advise you to compare this technology with a brain, because it?s the central place of the application. Lobes fill of the distinct functions: memories, reflexion, communication, etc. the same way, there is EJB various parts which fill the different roles.
EJB Presentation
What does EJB mean?
Written in the programming ?Java? language, an enterprise bean is a component on server side which encapsulates logic part of an application. Logic part is the code which achieves the goal of the application. Let us take the example of an application of inventory control, the enterprise beans could implement logic trade in methods called checkInventoryLevel() and orderProduct(). By calling upon these methods, the distant customers can reach the services of inventory provided by the application. As we will see at the time of EJB practical application, it is necessary to have an application server in order to lodge an application based on EJB. Indeed, this one must provide many mechanisms making it possible to manage the authorities of EJB, to make secure, share the application on a grid of calculation... etc. At the moment, we?ll base ourselves only on the specifications of EJB. The specifications are texts produced by expert groups from companies like Sun, IBM, Oracle... etc, in order to define bases common to all application servers.
EJB advantages
We?ll realize at the end of this essential that EJB make possible to separate the application layers in a clear way. Indeed, the functionalities suggested fit in an organization of the effective project. The separation of software in various parts makes it possible to understand what one is building: What will be the complete picture The responsibilities the subsystems and the developers How to manage the growth of the system Where the problems can appear? To prepare with changes in the needs or the approaches of implementation: Understand the limits of what you can really manage Know what you would have to change or build to satisfy Belong stable with the addition of new needs? ... Moreover, EJB are components of very high level. That means that the concepts that we will see are very powerful and are really simple to set up. Most of the time, the programmer will have only to take into account the constraint trade of his project, and to configure simple classes by means of some annotations. We will reuse without any reflection to account for the concepts like IO, RMI or JDBC, however, only the application server will have to use these technologies.
When should you use EJB?

You should use the ?enterprise beans? if your application must respect one of the following conditions: The application must be easy to update. To adapt to an increasingly significant number of users, you can need to distribute the components of an application through multiple machines. The enterprise beans of an application can operate on various machines, but also their localization will remain transparent for the customers
https://www.campus-booster.net/Booster/Pages/lectureSimpleViewer.aspx?lecture=814&PM=True
Page 1 of 100

The application must be transactional. EJB support the transactions, the mechanisms which control the access convergent to the shared objects The application will have different kinds of customers. With only some lines of code, the distant customers can easily locate EJB. These customers can be light, various and numerous.
17/10/09 18:17
EJB types
The table below summarizes the three types of EJB: Table 1. EJB Types Type Entity Timer Goal Represent an entity which exists in persistent storage Allows to plan tasks at precise hours
Session Carry out a task for a customer. Apply a service Web Message Acts like a listener for API Java Message Service, treating the asynchronous messages
We?ll have in this essential only about Beans of type Session, Message and Entity because they are usually used. Those of Timer type will be seen in a more advanced course on EJB.
EJB3 changelog
Specification 3 of EJB was elaborate in order to simplify the model of design of EJB. Here are the principal points which were simplified: Simplification of the definition of the interfaces, suppression of a good number of necessary points in version 2.1 (more need to inherit a super interface or class) Simplification for the creation of the class of Bean. Simplification of API for the access to the environment of Bean: definition by simple dependent injection Introduction of the use of the annotations as Java who are used in the place of the descriptor of deployment Entity Beans are simple POJOs annotated. The mapping relational-object can be declared in the form of annotations. Entity beans have greatly been improved during its third version. The specification defines that a bean written with API EJB3 must be able to be a client with a component writes with the API 2.1 (2 & 1 also). That has of course like objective to facilitate the migration of the existing applications or simply the use of those in the new applications. Knowing that EJB version 3 go back to semi-2006, it acts of a still young technology, which begins only its phase of adoption with industry. EJB 2 is still used even if that is not a doubt that they will migrate gradually towards the new specifications.
Concepts
We will approach, in this part, the whole of EJB concepts. We will explain the various types of existing EJB but also their differences and their uses.
EJB architecture
An EJB architecture is made up of at least 3-tiers: a customer (ex: Web, heavy customer...), applicative logic (EJBs) and a data base (ex: base relational, LDAP, ERP...).
In this architecture, EJB are located in the third "applicative logical". EJB implement logic trade of the application (for the Session part) and represent an abstraction of the access to the data base (for the Entity part). However, architecture EJB is before a whole evolutionary architecture. It is then possible to make evolve a simple application EJB to an application directed Business To Business being connected towards other systems of company.
Page 2 of 100
17/10/09 18:17
In this architecture, EJB are located in the third "applicative logical". EJB implement logic trade of the application (for the Session part) and represent an abstraction of the access to the data base (for the Entity part). However, architecture EJB is before a whole evolutionary architecture. It is then possible to make evolve a simple application EJB to an application directed Business To Business being connected towards other systems of company.
The preceding diagram is the structure of an EJB server. Even if the container has the most important role, it?s the server which switches the whole of the requests and manages the whole of the containers and services. The server must manage, moreover, one whole of services of infrastructure common to the whole of the containers or the services. The specification Java EE obliges the server to offer a service of directory JNDI and a service of transaction. Of course, application servers generally provide other services as a data base integrated or the security management. The goal is to facility the development, the deployment, etc... We can compare server EJB as an orchestra. The role of this server is to be the leader. It is him which directs the whole of the services and their cycle of life (starting, stop, pause...). Each part of the orchestra corresponds to a service (EJB, Transaction, Base data...). They all are independent, but they work together to produce a common result. EJB server EJB server manages whole of the services systems for EJB, and also manages the containers which authorities of EJB (called "beans") are carried out. EJB container A container, it is before all a "block box" which manages: communication with the services of infrastructure applications and their cycle of life related to the customers The container works of par with the server, providing, with them two, the environment of execution for EJB. The container simplifies the life of the developer thanks to a reduction of the codes to be built, a simplification of the treatments (automatic treatments), and a reduced maintenance (separation of the layers by levels of abstraction). Indeed, the container is at the same time an application managing of the applications but also a tool which generates code for each EJB. It is also the container which will make it possible the developer to use the services of infrastructure available within EJB server as connection to the database, the management of the transactions...
The main role of container EJB is, however, to manage the cycle of life of the applications EJB which are associated for him. It is him which deploys them, stops them and redeploys them, while managing their conformity with the
Page 3 of 100

specifications of the server. It also makes it possible to control the components which are with its load. Even if the container is the central point of the execution of EJB, the developers do not have to be worried some; it is a "block box" which, according to the specification, is carried out according to certain well defined events. To continue the metaphor of the orchestra, the container is the person who prepares the instruments, the partitions and the environment necessary to the musicians (represented by EJB).
17/10/09 18:17
What is a Session Bean?

A Bean Session is component an applicative side server making it possible to provide one or more services to various customer applications. A service is useful, for example, to recover the list of the products of a shop, to record a reservation or to check the validity of a stock. It can also represent a workflow. A Bean Session can be regarded as a storyboard in the world of cinematographic animation: it defines the successive stages in order to lead to a final objective. The Beans Session thus constitutes bricks of logic trade of an application. They treat the data and carry out the operations related to the logic of the company. Beans Sessions are as "frontage" between the customers and the data. Whereas Entity Bean (explained in the following chapter) is used to reach the data (addition, modification, suppression...). Bean Sessions are divided into two types: "Stateless" and "Statefull". State management There are two types of session beans: stateless and statefull. The choice of the type Stateless or Statefull is based on the interaction wished between the customer and the Bean Session.
Stateless session bean
Stateless Session Bean is a collection of services gathered around the same subject. Stateless means that the service is autonomous in its execution and thus which it does not depend on a particular context. The important point lies in the fact that no state is preserved between two invocations of methods. When a customer application calls a method of a Bean Session, this one carries out the method and turns over possibly the result. The execution is not worried what could be made before or what could be made afterwards. This type of execution is typically the same one as that of protocol HTTP (mode offline). Stateless Session Beans tend to being general in order to be able to be re-used in other contexts. The advantage of the Stateless type is its capacity to be gone up in load. Indeed, several customers use the same authority of EJB in a concurrent way.
Stateful session bean
Statefull Session Bean is an extension of the customer application. It introduces the concept of session between the customer and the server. One speaks precisely about conversational state to qualify this type of communication. So a method called on EJB can read or modify information on the conversational state. EJB is divided by all the methods for a single customer. Contrary to the Stateless type, Statefull Session Beans tend to being specific to the application. The virtual caddie is the most common example to illustrate the use of Statefull Session Bean.
In the case of Statefull, each customer is related to an authority of EJB (fig. 3.2). This type of Bean Session thus consumes more memory that the Stateless type. Moreover, the work and the maintenance of association constitute an important additional task for the container. It results from it a worse rise in load and sometimes degradation from the performances when an application uses the Statefull type wrongly and without reason. As we detailed at the beginning of this part, each authority of Statefull Session Bean is associated to a single customer. This type of component maintains the state conversational with the customer, the variables of authorities of this component are then related to the customer and their values preserved of a call of method at another. However, that doesn?t mean that in any case that Statefull Session Bean is persistent. The server of application can use a system of plug ("swap") for preoccupations with an optimization of memory (concept of passivation) Statefull Session Bean is usually used to manage a process being carried out in several stages (purchases on a going site, to reserve a travel, to send a newsletter...).
Page 4 of 100

Let us take the example of a site of trade online. The basket can be modeled thanks to Statefull Session Bean. A sale is carried out after several stages: Choice of the articles Creation of a clients' account or use of an existing account Choice of the payment of the order Payment Recording of the order It is imperative to safeguard the state of the conversation between these various stages in order not to lose information.
17/10/09 18:17
Access to the Session Bean Beyond the simple delimitation of the various applicative layers, EJB define the way in which the various announcers of year structures Java EE interact. They define, moreover, the possibilities offered to the various customers (Java application, applet, application being carried out one the same server of applications) and the methods of communication. Thus, it will possible to define EJB according to two prospective customers for the customer: local sight (room) has and has distant sight (remote). Beyond the simple delimitation of the various applicative layers, EJB define the way in which the various speakers of architecture Java EE interact. They define, moreover, the possibilities offered to the various customers (Java application, applet, application being carried out on the same server of applications) and the methods of communication. Thus, it will be possible to define EJB according to two prospects for the customer: a local sight (room) and a distant sight (remote).
Local visibility
By adopting has local sight (room) for has EJB, any customer carried out in the same virtual machine (another EJB, servlet ...) is whitebait to call the methods of this EJB. In this sight, the calls of method of EJB by the customer are carried out have in any traditional Java application (Java SE). The arguments passed by possible reference and it are, for the customer to directly modify the recovered objects. He results has weaker demarcation from it from EJB with respect to his customers. Unfavorable it?s necessary then to consider that various customers handle the same object At the same time and thus to anticipate the effects that that edge induce. One the other hand, the uses of has local sight makes it possible to optimize the performances of the server of application and to minimize the resources. This one does not cuts then to Be occupied of specificities related to transport via the network (not of serialization of the objects, No communication network...).
Remote visibility
By adopting a distant sight (remote), a EJB places at the disposal its methods with customers being carried out on different virtual machines, and thus on different physical machines (applet, applications Java, etc...). Within the framework of a distant sight, the demarcations are stronger between an EJB and its customer. The calls of methods are done via technology RMI, the arguments and values of return must be serialized and are not transmitted any more by reference. It is then more possible only one customer modifies the same object of another customer, and it is thus easier to delimit the various fields of safety. On the other hand, the use of a distant sight has also disadvantages. The objects having to be "transportable" remotely, the container owes serialize/unserialize these objects to transmit them via the network. It results from it from the higher processing times compared to the local calls.
Web services visibility
The webservices are spread more and more on Internet, because they make it possible to use any service starting from any language. It is possible to specify the visibility of your EJB with the webservice type so that it can be used with the manner of a webservice. However, this choice is restricted with EJB of the type Stateless Session Bean. This technology misses maturity however and must for the moment to remain on the level of the concerns of technological survey.
How to choose your connection?
The adoption of a local or distant sight decides at the time of the creation of EJB. It is completely possible simultaneously to consider the use of these two sights, but it will be necessary to take into account the fact that they are not completely equivalent (in particular on the level of safety with the passages by reference/valor). The principal difference between these two types is undoubtedly the local access or the remote access. If the customer application is carried out within the same virtual machine then the local sight certainly will be adapted and conversely for the remote sight. The choice should not be generic, but must be made compared to the needs for the application. It is however possible to support the local accesses while placing an intermediary (the container Web) between EJB and
Page 5 of 100

the distant customer. The sight webservice, as for it, is to be used when the customer is not written as Java or when you wish to render your service most open possible. Typically, if you wish to give the possibility to your purchasers of consulting your catalogue of products in any manner, it can be judicious to give them the access to such a Web Service. To compare this concept with an orchestra, the local side would be that of a spectator present in the room and the remote side that of a spectator listening to on his radio the repeat broadcast placed at the disposal by the orchestra. The side webservice would be that of an external TV channel, downloading the recording in the complete concert, placed at the disposal by the orchestra (" Business to Business "). When to use a Session Bean ? Here some conditions concerning the use of the Beans Session in a system of company: At any moment, only one customer has access to the authority of the Bean Session. The state of Bean is not persistent, it exists only for one short duration (approximately a few hours). The service can be accessible also via a service Web. Statefull Session Beans are suitable if one of the following conditions (not exhaustive) is true: The state of Bean represents the interaction between Bean and a particular customer. Bean must store the information concerning the customer during the execution of the methods. Bean makes the connection between the customer and other components of the application, presenting a sight simplified at the customer. In slide, Bean controls the workflow of several Beans Company (it is thus a frontage). To improve performances, you can choose to use Stateless Session Bean if it has one of these characteristics: The state of Bean does not have a data specific to a customer. In only one call of method, Bean achieves a generic task for all the customers. For example, to send an email confirms an order on line. Bean recovers of a data base a unit of data in reading alone which are often used by the customers. Such Bean, for example, could recover the lines of a table which represent the products which are on sale this month. The choice of the type of Bean Session is not always obvious. However, in a large majority of the cases, the services offered are ?static?, i.e. independent of the customer who calls them. In such cases, prefer the Stateless type by defect.
17/10/09 18:17
What is a Message Driven Bean?

Presentation Within an information system of company, two applications can need to communicate. By communication, it is necessary to include/understand a sending of data directly interpretable and usable by the other applications. They are the Message Driven Beans which makes it possible to treat the messages coming from other applications. The concept of MDB (Message Driven Bean) was introduced with EJB 2.0 in order to treat the messages coming from a supplier JMS (Java Message Service). Since version 2.1, the Beans Messages support any system of transport and are thus independent of JMS. Specification EJB 3.0 does not offer really new functionality, but largely simplifies the development of these components. Send a message with JMS All the compatible servers of application EJB 3.0 must support JMS. Many editors provide their own implementation JMS, others provide the supports to question other implementations JMS. In all the cases, a supplier JMS is inevitable to use the Bean Message. JMS is the API one used for the access to a system of transport of company. It is the solution Java EE with the concept of the MOM (Message Oriented Middleware). This system allows the exchange of messages between various distant applications. The servers of transport are often ignored (contrary to the database servers), although they are numerous. One finds MQSeries from IBM, JBoss Messaging (in the past JBoss MQ), One Message Tail of Sun Microsystem... The applications using JMS are independent of the type of server to which they are connected since they use the API JMS. The applications generally use JMS in architectures of the type B2B (Business to Business). Indeed, this API makes it possible to interconnect any system using the principle of transport where the sending and the reception of message are asynchronous. That means that the applications communicating via JMS cannot be carried out at the same time, on the same principle as the system of electronic mail (email). When the sender sends a request (by an email), then it doesn?t receive the answer directly. It may be that it never receives answer, or only one acknowledgement of delivery.
Architecture JMS is made up of various elements: a supplier consumer
Page 6 of 100
17/10/09 18:17
messages destinations Thus, a supplieris the element has the load of the delivery of the messages between the various speakers. He occupies himself of treating the sendings and making so that they are received. A customer is an application or intervening component of application at the time of the exchanges. He sends or receives the messages. A message is, as its name indicates it, the element which will forward via a communication between the customers. A supplier is always used as intermediary; one thus does not send them directly customer to another. The destinations are objects configured on the level of the supplier which are at disposal of the customers and who will be used by the latter for the sending and the reception of the messages. To schematize, one can say that they are " letter boxes " in which the messages are placed while waiting for that a customer comes to claim them. When use it? An important point in this architecture is that it allows a communication slightly coupled between the customers: a customer is not worried identity of sound or his correspondents not of their possible state. Moreover, this system can work in heterogeneous environment (C++ application, Java...). Message transmission facility JMS offers two models of transport: pointtopoint and publication/subscription. In a simple way, the pointtopoint model represents a relation ?One to One? between a message and a recipient whereas the model publication/ subscription is represented by a connection ?One to Many?.
Peer to Peer (P2P)
The pointtopoint model makes it possible to connect the customer applications between them via a queue (tail). It is exactly like the principle of a pile. The messages are sent and piled up. When a customer application (consuming) is free, it then receives the piled up messages.
In a pointtopoint model a message is transmitted only to only one application.

Publishion / Subscription
In this model, a producer can send a message to several consumers by the means of a subject (topic). Each consumer must however have been registered beforehand on this subject if not it does not receive anything.
This model can be assimilated to a hub (material physique of network). Each new message is broadcast towards each registered consumer. The producer is independent owing to the fact that the message was received by the consumers. There are two types of subscription: temporary and durable. In the temporary case, the consumers receive the messages as long as they are connected to the subject. In the case of a durable subscription, one obliges the supplier to record the messages at the time of a disconnection, and to send them at the time of the new connection of the consumer.
Which mode to choose?
A common problem for the architects is of knowing which model to use. Indeed, after some reflections, it proves that it is possible to make the same thing whatever the model used. However, each of the two models has interesting characteristics. JMS provides an access on these two types of models bus to its development, certain companies used the pointtopoint
Page 7 of 100

model and others used the model of subscription. In the majority of the cases, the selected model depends on the use which one wishes to make. The pointtopoint model will be preferred when it be wished that only one milked recipient the message and to be sure that it is treated. Conversely, the model of subscription is less restrictive and is used more particularly for the flow of information which can be used by any customer.
17/10/09 18:17
What is an Entity Bean?

Entity Beans were created to simplify the management of the data on the level of an application, but also to facilitate the safeguard in data base. More concretely, these Entity Beans enable you to deal with the persistence of the data of your application in one or more data sources, while keeping the relations between those. These components thus establish the relation between your application and your data bases. Contrary to the Beans Session, the data of Entity Bean are preserved, even after the stop of the application. The application data are typically: users, invoices, products, addresses... In the Java world, and more generally in the world object, it is common to use classes for each type of objects used. One often speaks about trade object or entity (English Entity) to represent the characteristics of these objects.
The connection between the data and the application by an object is called the mapping(to connect). The figure above presents the mapping between the table User and User classifies it. One speaks about Mapping Object/Relational when one connects, in this manner, a relational database with an Object application.
Warning
The use of Entity Beans makes it possible to represent an entity of the application and not functionality. For example, User would be Entity Bean, but User Subscription would be a Bean Session; a user being dedicated to remain persistent, whereas the inscription of the user is a service. Contrary to the Beans Session, the data of Entity Beans generally have a long lifespan; they are recorded and stored in systems of persistence (bases data). The concept is older in EJB, but it starts to appear in the applications Java SE, with the appearance of container lighter. Persistence While shortening, it is possible to say that the object to be made persistent, via Mapping Objet/ Relational, corresponds to a table. Each property of this object is related to a field of the table. Each authority of this object generally represents a recording of the table. However, it is possible that Entity Bean is distributed on several tables. Conversely, a table in a data base gathers a whole of fields. These fields represent either of information directly related to the table, or of the bonds towards other tables. All this information is not therefore the direct properties of the object in question. Entity Bean follows the same principle and must all have a single identifier (key primary education). Entity Bean AccountInfo, for example, can be identified starting from its account number accountId. This single identifier makes it possible the application to find the data of Entity Bean associated. Entity Bean User, for example, is characterized by properties such as: " name ", " first name ", " email ", " telephone "... These properties are called: persistent fields. These properties are ampped (dependent) with the fields of the associated table. During the execution of the program, container EJB automatically synchronizes the state of these properties with the data base. Like a table, Entity Bean has relational fields. However, a great difference exists. A relational field is represented, in Entity Bean, by a property whose type is another Entity Bean (fig. 4.2). One speaks about aggregation, in programming object. With the opposite, a table is related to another table by a foreign key (fig. 4.3).
Instance creation The creation of authority of an entity is done simply by the simple instantiation of the class by the operator new. However the persistence of the object created is carried out with API EntityManager. We will see that in detail more below. Relations There are 4 possible relations between Entity Beans: One To One (one by one): If a user can have one and single account then the relation between the user and his account is of type ?One To One? One To Many (with several) and Many To One (several with one):
Page 8 of 100
17/10/09 18:17
A user can have several wallets whereas a wallet is held by only one user. The relation between Wallet and User is of type ?Many To One? and the relation between User and Wallet is of type ?One To Many?. Many To Many (several with several): A user has several leisures (hobby) and leisure can be shared with several users. In this case, the relation is of type ?Many To Many? between user and user.
In the application of example, a user has several wallets of actions. This connection is represented by a relation ?One To Many?. Heritage An entity can inherit another, knowing that an entity can as well be an abstract class (see the key word ?abstract?) that a concrete class (notabstract). To illustrate this concept, we can see above the diagram of the entities of the application. Indeed, the class ? FinancialProduct? is abstract. Then, ?Stock? and ?Jump? inherit this class. Indeed, in our software of manager of financial products, those can as well be actions sides out of purse (?English stock?), or obligations (?English jump?). There are 3 strategies of ?mapping?: a table for a hierarchy of class a table by concrete class Strategy consisting in separating the specific fields from a class girl in a table separated compared to the table containing the data of the table relationship. A junction is then made for instantiate the class girl. We will study the advantages and the disadvantages of each one of these choices later, but retain for the moment which that will have of importance only on the level of the performances. Shared access The entity beans can be divided by multiple customers. As the customers could want to change the same data, it is important that the entity beans work inside transactions. Typically, the container of EJB provides the management of transaction. In this case, you specify the attributes of the transaction in the descriptor of deployment of the bean. You do not need to code the limits of the transaction in the bean; the container defines the limits for you. Persistence unit Integral part of the framework Java EE 5, the unit of persistence is it ?limps black? which makes it possible to return persisting Entity Beans. More than one simple supplier of persistence, this one will make it possible the developers to optimize their applications according to the management of their Entity Beans. The unit of persistence is the key element of the management of Entity Beans within an application.
Database connection
The specification defines a file which gathers the whole of information of persistence. You must name this file: ? persistence.xml? and to place this file in repertory ?METAINF?, with the root of the project. This file will be read by container EJB at the time of the deployment of the application. The container then creates an authority of the supplier of persistence with the required parameters.
Warning
You must name correctly the file ?persistence.xml?. If the name does not correspond, the container will not associate any context of persistence in the application. A unit of persistence (Persistence Links) is characterized by the following points: A whole of Entity Beans A supplier of persistence, because various manufacturers propose their implementation of the engine of persistence. For JBoss it acts of Hibernate, and Oracle proposes TopLink. A data source, like Oracle, PostGreSQL, MySQL, SQL Server... or Derby (a base of data functional, very light, and written as Java).
Page 9 of 100

Persistence Manager It acts of a device managing persistence between the data and the unit of persistence. Entity Manager being an interface, the class of implementation is different according to the supplier used (defined in the file ?persistence.xml? with the beacon < provider >). By defect, it is the container which will instantiate EntityManager and which will manage its cycle of life. When to use Entity Beans? Entity Beans are carried out in the container EJB, which brings to the developers of many services. The principal service is, of course, the management of the persistence which manages the whole of the access to the data in the memory or the data sources. The use of this service, and thus of Entity Beans, gets multiple comparative advantages with the direct access to the data base. This solution brings a simple mechanism for the access and the modification of the data. Indeed, it is easier, to modify the first name of a user within your application, to call the method User.setFirstName() to carry out a rough request SQL. Moreover, Entity Beans being standardized, your code is clear and more easily reusable (the definition of a user is found, for example, in the majority of the applications). Entity Bean being an EJB, it inherits the services such as the management of the transactions, of safety... as well as many development tools optimized for their creation.
17/10/09 18:17
The client
The third customer is represented by the applications connecting itself to EJB. These applications are generally written as Java; however, it is also possible to be connected to a EJB with a customer written in another language via an access by Service Web (fig. 1.10). The Java customers generally use JNDI and RMI to connect and call the methods of EJB. So they can as well be fenestrated graphic applications (called rich customers), other EJB, applications internal, and, obviously, light customers (Web navigator). It is also possible to make communicate the external systems with a transport interapplication, like JMS.
The client is the public which listens to the concert. The client made the request to return in the room and paid his ticket with case (RMI), by a retailer (HTTP, Services Web...) or by small advertisements (JMS). EJB being components server, a customer must obligatorily be set up to be able to communicate with those. These customers can take several forms: An application with or without graphic interface An applet A servlet in a Web application A EJB
Note
You can also call a EJB in a page JSP. Nevertheless, this technique is misadvised because it does not respect the good principles of the pattern MVC (Model Seen Controller). This model requires that the access to the Model (service) be done since the Controller (a servlet for example) and not starting from Sight (JSP). Knowing that, EJB components are divided by directories. Then the customer locates them via the API JNDI and their name JNDI. The deployed components are recorded in the directory of the server. Only JNDI pilot (called service provider) changes one implementation to another. The calls of distant methods are done by RMI (Remote Method Invocation) whereas the calls of local methods are done directly in the JVM of the server.
Page 10 of 100
17/10/09 18:17
The customer recovers a reference (implementing the interface trade) EJB which it wishes to use. This one can then call the methods of the object recovered without worrying about the constraints of communication. Indeed, the call of a method is automatically transmitted to the authority of EJB in the container (generally by a system of proxy). This authority treats the method and turns over the result to the customer. The creation of the proxy is with the load of the container and remains completely transparent for the customer.
Theory
In this part,we are going to study the various components that we must provide for a EJB. We will describe in a generic way all the rules to be respected. We will observe these rules in the next chapter.
The various steps in creation of a Bean Session

Interfaces A client can reach a Bean Session only through the methods defined in the interfaces of the bean. These interfaces define the view that the client has on the bean. Neither the Message Driven Beans, nor Entity Beans need interface.
Distant clients
A distant client of a Bean Session refers following: It can work on a different machine and a different Java Virtual Machine (JVM) from the entreprise bean which it reach It can be a web component, an J2EE client application, or an other EJB
Local clients
A local client has the following characteristics: It must be executed on the same JVM as the EJB which it reaches. It can be a Web component or another EJB They must be deployed together, in the same EAR (equivalent of the JAR for the entreprise applications)
Client of the WebService type
The Services Web are spread more and more on Internet, because they allow to use any service independently of the platform or the language. It is possible to specify the visibility of your EJB with the webservice type so that it can be used as a Service Web. However, this choice is restricted with the EJB of the type Stateless Session Bean.
To choose between a distant and local access
The main difference between these two types is undoubtedly the local access or the remote access. If the client application is executed in the same virtual machine then the local view will be more adapted. The choice should not be generic, but must for the needs of the application. It is however possible to support the local accesses while placing an intermediary (the container Web) between the EJB and the distant customer.
Note
In Local mode, the parameters are passed by reference, and in Remote mode, they are passed by value The webservice view is to be used when the client is not written in Java or when you wish to publish your service most open possible. Typically, if you wish to give the possibility to your purchasers of consulting your catalogue of products in any manner, it can be judicious to give them the access this Service Web. To take again our comparison with an orchestra, the local view would be the spectator in the room and the distant view, would be an spectator listening on his radio the repeat broadcast placed at the disposal by the orchestra. The webservice view would be an external chain TV, downloading the recording in the complete concert, placed at the disposal by the orchestra (?Business to Business?). Bean Class (implementation) The bean class of an EJB is the class of execution of the Bean Session. Indeed, it is in this class that you must program logic trade. The whole of the methods declared in the interfaces (distant/local) will have to be implemented in this class.
Page 11 of 100
17/10/09 18:17
Annotations The annotations are marks in the Java code, which make it possible to configure the application. In the case of Stateless Bean Sessions, we will place @Stateless on the level of the class of implementation. For Stateful Bean Session, it is about @Stateful . We will study them in detail when we write our own EJB. Descriptors of deployment We?ll find, in the specification, the files:
application.xml
being used to declare the whole of the modules integrated in a file ?.ear?. You must specify your archive of persistence in your file application.xml with the following lines:
<application xmlns="http://java.sun.com/xml/ns/j2ee" version="1.4" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance" xsi:schemaLocation="http://java.sun.com /xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/application_1_4.xsd"> <displayname>StockManager</displayname> <description>Demo application</description> <module> <ejb>StockManagerEJB.jar</ejb> </module> <module> <web> <weburi>StockManagerWAR.war</weburi> <contextroot>/stockmanager</contextroot> </web> </module> </application> ejb-jar.xml
configure the EJB in a module of a ?.jar? file (optional if the descriptors of deployment related to the applications servers are specific and depend only of them) Sun Application Server uses the files sunapplication.xml (ear), sunejb.xml (jar), sunweb.xml (war). JBoss uses the files jbossapplication.xml (ear), jboss.xml and jbosscmpjdbc.xml (jar), jbossweb.xml (war). These files make it possible to use advanced functionalities of the server of applications which are not integrated into the specifications.
Warning
The use of nonstandard functionalities (except specification) involves problems of portability of a server of applications towards another Assemblage (ou Packaging) To deliver an application Java EE 5 you must create an enterprive archival file (EAR). It is a standard archival file with the extension ?.ear? which gathers a lot?s of modules EJB, Web, Application client... like showed the following diagram (2.5).
Each archival file (ear, war, jar or rar) contains a descriptor of deployment organized and structured on model XML. This one makes it possible to define the parameters of deployment of an application (ear) or a module. Deployment The step of deployment for the developer is generally very simple. It is enough to place the packaged file in a special repertory of the server of application or to use the administration of this one. JBoss requires simply that the file is put in the folder ?deploy? of the current configuration ($ {jboss.home} /server/ {configuration} /deploy Glassfish allows the deployment by the interface of administration Web or the administration command line or by a folder ?autodeploy?. The task is however more difficult for the server of application. This one must read the contents of the archive, scan the classes (in order to detect the annotated components), mapper Entity Bean at the database, to lay down the policy of security (if it is declared), generate the classes (proxy,etc.) according to specificities of the supplier. We will more develop the subject of the servers of application in the final chapter Client Let us start by remember that the EJB are distributed objects. They thus are in a system of naming and relation
Page 12 of 100

client/server. The client must carry out various steps: To parameterize the environment client. Connection to the server of naming of the server of application (JNDI) To recover, with the URL, the stub one corresponding to the class Home of EJB (JNDI/RMI) Call distants methods. We will see in detail the whole of APIs to be used for each one of these stages. Conventions of nomenclature The enterprise beans are composed of multiple elements, so it is useful to follow a convention of nomenclature for your applications. The following table summarizes conventions (the example is taken on a bean representing an Account ? Account?). Table 1. Convention of nomenclature of Enterprise Beans Element Nom de l'Enterprise Bean EJB JAR Interface Abstract shema Syntax <name>JAR <name> <name> Exemple AccountJAR Account Account
17/10/09 18:17
<name>Bean AccountBean
Classe de l'Enterprise Bean <name>Bean AccountBean
Specification of a Bean Session

The elements to be set up for a Bean Session are: The class Bean The interface business The class Bean We use the annotations @Remote or @Local to define respectively if the Bean Session provides the methods to distant or local clients. It is the same for the types of Beans Session, with the annotations @Stateless or @Stateful .
@Stateful @Remote({ RichClientService.class }) public class RichClientServiceBean implements RichClientService { }
In this example, the class is annotated with @Stateful in order to declare it as Stateful Session Bean. The annotation @Remote makes it possible to specify the distant interfaces usable by clients. Cycle of life
Stateless
Since a stateless session bean is never ?passivated?, its cycle of life has only two states: ?does not exist? and ?ready? for the call of methods trades:
The Beans Session support the following callback interceptors:

@PostConstruct
The method on which this annotation is put is called when all the dependences of injection carried out by the container and before the first call of the method trade.
@PreDestroy
The method on which this annotation is put is called at the time when the instance of Bean is destroyed (during the suppression of Bean or with the stop of the application).
Stateful
The diagram below illustrates the differents steps for a Bean Session of the Stateful type during its life.
Page 13 of 100

The session bean support the following callback event:
@PrePassivate (Stateful only)
17/10/09 18:17
Allows to specify a method which will be called by container EJB when Bean was inactive and it was considered to pass this one in a serialized state. This method must be sure that the resources maintained in instance are released or serializables. We speaks about ?passivation?. The interest of this principle is to release the memory employed by unutilised Stateful for the moment. The container then can serialize the instance on an external medium (hard disk...).
@PostActivate (Stateful only)
It?s the reverses of @PrePassivate . This annotation allow to specify the method which will be called by the container when a Bean must be reactivated from its state of passivation. Bean will have to find an operational state by recovering the resources released during ?passivation?. We speaks about ?activation?.
The ?passivated? state is reserved for Stateful Session Beans because they are the only ones to share a state with the customer. The life cycle of this component starts with the first call of a business method. The container then creates an instance with the Class.newInstance method (). It injects the dependences and calls the methods annotated with @PostConstruct . The great difference with the Stateless type is that Stateful integrates the concept of ?passivation?. The implementation of this concept is specific to the container and can vary from one client to another. In all the cases, the container calls the methods annotated with @PrePassivate and @PostActivate at the time of the passivation and the activation of the component. The instance is removed when the customer calls a method annotated with @Remove or when the time assigned for the session is exceeded (?timeout?). Exemple Here a very simple example of SessionBean (stateless type). The interface should of course be defined that our bean will implement. Here we define simply the Remote interface which contains only one method: getHello (). Moreover let us annotate it with the annotation @Remote in order to declare it like distant interface. Here the code of the distant interface (Remote):
import javax.ejb.Remote; @Remote public interface RemoteHello { public String getHello(); }
The bean class implements the preceding interface and is annotated by @Stateless in order to declared it as Session Bean Stateless. Here the code of this class:
import javax.ejb.Stateless; import com.society.testejb3.interfaces.RemoteHello; @Stateless public class HelloBean implements RemoteHello { public String getHello() { return "Hello world"; } }
Dependence between Beans Session As we see previously with Entity Manager, you can specify to the container that your EJB is on another. The container will be given the responsability automatically to inject the required instance. It?s why, you just have to annotate the property with @EJB. Here, an example using this annotation:
@Stateful @Remote( { RichClientService.class }) public class RichClientServiceBean implements RichClientService { @EJB private CommonService commonService; }
The RichClientServiceBean class defines a variable of instance commonService whose type is CommonService (the business interface related to the EJB). With the annotation @EJB positioned on this property, the container automatically injects an instance of the EJB ( CommonServiceBean ) when the instanciation of the EJB RichClientServiceBean . I.e. it makes, in your place, JNDI research and the automatic initialization of the dependence towards this EJB. For certain more complex cases, the annotation @EJB admits attributes which allow to specify the localization of the EJB.
Page 14 of 100
17/10/09 18:17
beanName
Specify the name of the EJB (specified by the attribute name of the annotations @Stateless , @Stateful or in the descriptor of deployment with the markup <ejbname> ).
beanInterface
Specify the business interface that we wish to use. This attribute is mainly indicated when you use an interface related of the business interface implemented by Bean. The default interface is used by the variable which is subject to the injection
mappedBy
Specify JNDI name to be used to seek the instance of Bean. EJB3 Specification wishes to hide these JNDI calls which often diverted the developers. However, the injection has its limits and is available only within one container.
Warning
the annotation @EJB in a rich customer application (console or graph) is available only when this one is launched in the ? Application Container Client? (AAC). The installation of this type of application is explained hereafter.
The client view

The client of a EJB does not work directly with EJB system. Moreover, the client reaches with interfaces to beans and their business logic. These interfaces gather the API JNDI (Java Naming Directory Interface) and an API EJB Client. While JNDI is used to locate and reach the EJB in a transparent way, API EJB Client is a whole of interfaces and classes which the developer uses to work with the beans. We will see in this chapter several small examples of code allowing to locate/reach/work with the beans. You will find a complete code in the chapter: EJB with practice. JNDI is a standard in java. It allow to standardize connection to a service of directory, like does it JDBC for databases. There are many suppliers of directory, each one of them must provide its own driver for its type of directory (LDAP, File system, EJB...). Localization of bean with JNDI Here an example allowing a client to recover a reference towards the Session Bean RichClientServiceBean .
try { Context ctx = new InitialContext(); ctx.put("java.naming.factory.initial","org.jnp.interfaces.NamingContextFactory"); ctx.put("java.naming.factory.url.pkgs","org.jboss.naming:org.jnp.interfaces"); ctx.put("java.naming.provider.url","127.0.0.1:1099"); // le nom JNDI par dfaut est // "Nom du fichier EAR/Nom de la classe du bean/type accs : local/remote" richClientService = (RichClientService) ctx.lookup("StockManager/RichClientServiceBean/remote"); } catch (NamingException e) { // gestion des erreurs }
The object ?Context? allow to initialize the parameters of connection to the directory to communicate with its. Among the parameters of the example, we finds in particular the URL of the register, here with the 127.0.0.1 address. Thus when the server of application is not on the same machine that the client, this adresse IP should be modified. Moreover, the first two parameters are specific to JBoss and the values correspond to objects located in the bookshops client of this server. The principle is the same for a client in a Web application, an application console or another EJB.
Use of JMS and the Message Driven Bean

ConnectionFactory and Destination To work with JMS, the first stage is to connect itself to supplier JMS. It is necessary to recover a ConnectionFactory object with JNDI which makes connection possible with the supplier. This object can be compared to a DataSource (in JDBC). Indeed, in the same way that DataSource provides a connection JDBC, ConnectionFactory provides a connection JMS to the service of routing of message. Here an example detailing the recovery of ConnectionFactory and a Destination:
Context jndiContext = new InitialContext(); ConnectionFactory connectionFactory = (ConnectionFactory) jndiContext.lookup("ConnectionFactory"); Destination destination = (Destination) jndiContext.lookup("queue/MyQueue");
The other element to recover is the destination. It represents the place on which the application wishes to work (sending or reception of message). We will see in the following part that there are two types of destinations: topics and tails. Connection and Session The ConnectionFactory object makes it possible to create a connection with supplier JMS. Once connection created, it is used to create a session.
Connection cnx = connectionFactory.createConnection(); Session session = cnx.createSession(true, 0);
The session is used to group the operations of sendings and receptions of messages. In the majority of the cases, a single session is sufficient. The creation of several sessions is useful only in the case of ?multithread? application which produce and receive messages at the same time. Indeed, the Session object is ?threadsafe?, i.e. its methods do not authorize the concurent access. Generally, the thread which creates the Session object uses the producer and the consumer of this session.
Page 15 of 100

The method createSession() need two parameters:
createSession (boolean transacted, int acknowledge)
17/10/09 18:17
However, the specification indicates that the value of these arguments is ignored within container EJB. Indeed, this one manages the transactions and the acknowledgements of delivery according to the parameters of deployment.
Warning
Certain suppliers do not adhere completely to the specification and are not unaware of the parameters. The good practices of development encourage to close connections once the work is completed.
Connection cnx = connectionFactory.createConnection(); // [...] cnx.close();
MessageProducer and MessageConsumer The last step is the sending and the reception of messages. It is necessary to create objects of the type MessageProducer and MessageConsumer respectively to send and receive messages.
MessageProducer producer = session.createProducer(destination); MessageConsumer consumer = session.createConsumer(destination);
Each method takes in parameter the destination on which the object is connected. Type of Message In JMS, a message is a Java object made up of a heading and a body. The heading is composed of information of destination, expiry, priority... The body of the message contains data being able to be various types: Text with TextMessage . Serialized object with ObjectMessage . Map with MapMessage . Each one of these types of messages inherits javax.jms.Message . Let us take the case of MapMessage , where a message asks for the purchase of 250 actions of the company ? JavaCorp?. This information would be transmitted in an object of the MapMessage type:
MapMessage mapMsg = session.createMapMessage() ; mapMsg.setInt("action", StockAction.BUY_STOCK) ; mapMsg.setString("company","JavaCorp") ; mapMsg.setInt("number",250); producer.send(mapMsg);
Another solution consists in sending a serializable object directly :

StockAction stock = new StockAction(); stock.setAction(StockAction.BUY_STOCK); stock.setCompany("JavaCorp"); stock.setNumber(250); ObjectMessage objectMsg = session.createObjectMessage(); objectMsg.setObject(stock); queueSender.send(objectMsg);
Two other types of messages are available to treat array of bytes and the primitive types, which are BytesMessage and StreamMessage . Those use data flows. Clients Applications There are various interfaces according to the model of message used. However an interface common to both models exists and provides a whole of sufficient methods in the majority of the cases!
Producing client
Here an example of client application which is used to produce and to send messages.
public class JMSSender { public void sendMessage(String text) throws Exception { Context ctx = new InitialContext(); ConnectionFactory connectionFactory = (ConnectionFactory) ctx.lookup("ConnectionFactory"); Destination destination = (Destination) ctx.lookup("queue/StockValue"); Connection cnx = connectionFactory.createConnection(); Session session = cnx.createSession(false, Session.AUTO_ACKNOWLEDGE); MessageProducer producer = session.createProducer(destination); TextMessage message = session.createTextMessage(); producer.send(message); cnx.close(); } }
We find the whole of the components quoted previously ( ConnectionFactory , Destination , Session ...). The properties for the creation of Context JNDI are dependent on supplier JMS used. Here values used for GlassFish:
Hashtable hashtable = new Hashtable(); hashtable.put("java.naming.factory.initial", "com.sun.enterprise.naming.SerialInitContextFactory"); hashtable.put("java.naming.factory.url.pkgs", "com.sun.enterprise.naming"); hashtable.put("java.naming.provider.url", "iiop://localhost:1050/"); Context jndiContext = new InitialContext(hashtable);
Here those for JBoss:

Hashtable hashtable = new Hashtable();
Page 16 of 100
17/10/09 18:17
hashtable.put("java.naming.factory.initial", "org.jnp.interfaces.NamingContextFactory"); hashtable.put("java.naming.factory.url.pkgs", "com.sun.enterprise.naming"); hashtable.put("java.naming.provider.url", "localhost:1099"); Context jndiContext = new InitialContext(hashtable);
Note
These data are as an indication and can change according to the evolution of the various versions of these server of application. Here a summary table of the specific interfaces which can be used for a message of the ?pointto point? type: Table 2. Correspondence between the generic interfaces and those specific to the ?pointtopoint? transport Generic Destination Session MessageProducer Specific point to point Queue QueueSession QueueSender
ConnectionFactory QueueConnectionFactory
Here a summary table of the specific interfaces which can be used for a transport of the type ?subscription?: Table 3. Correspondence between the generic interfaces and those specific to the transport by ?subscription? Generic Connection Destination Session MessageProducer Specific subscription TopicConnection Topic TopicSession TopicPublisher
ConnectionFactory TopicConnectionFactory
Consuming client
The code of the consumer is very similar to the preceding code. Indeed, the only things which differ are the recovery of MessageConsumer and the sending of the message.
public class JMSReceiver { public void receiveMessage() throws Exception { Context ctx = new InitialContext(); ConnectionFactory connectionFactory = (ConnectionFactory) ctx.lookup("ConnectionFactory"); Destination destination = (Destination) ctx.lookup("queue/StockValue"); Connection cnx = connectionFactory.createConnection(); Session session = cnx.createSession(false, Session.AUTO_ACKNOWLEDGE); MessageConsumer consumer = session.createConsumer(destination); consumer.setMessageListener(new MessageListener() { public void onMessage(Message message) { System.out.println(message); } }); cnx.start(); } }
In this example, we use the concept of listener avoiding any blocking of the application when the reception of a message. For that, we must implement the MessageListener interface. The method onMessage (Message message) is then called automatically at the time of the reception of a message
Warning
Do not forget to start connection with the method start() if not no message will be received. By the same way as the producer, the consumer can use more specific interfaces for each model of transport. Here a summary table of the specific interfaces which can be used for a transport of the ?pointto point? type: Table 4. Correspondence between the generic interfaces and those specific to the ?pointtopoint? transport Generic Specific point to point
MessageConsumer QueueReceiver
Here a summary table of the specific interfaces which can be used for a standard transport ?subscription?: Table 5. Correspondence between the generic interfaces and those specific to the transport by ?subscription? Generic Specific subscription
MessageConsumer TopicSuscriber
Writing of a Message Driven Bean (consuming messages)

The class of Bean Now in EJB 3, it is not obligatory any more to implement the MessageDrivenBean interface. Only the annotation @MessageDriven is necessary to define your class as MDB. But the implementation of MessageListener is necessary if the MDB works with JMS.
@MessageDriven(name = "StockValueListener",
Page 17 of 100
17/10/09 18:17
activationConfig = { @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Topic"), @ActivationConfigProperty(propertyName = "destination", propertyValue = "topic/StockValueTopic")} ) public class StockValueListenerBean implements MessageListener { @Resource private MessageDrivenContext ctx; public void onMessage(Message message) { // TODO => update stock value procedure } }
All is realizable with the annotations. The annotation @MessageDriven makes it possible to define the name of the MDB within the container (attribute name). The attribute activationConfig allow to configure the properties of the MDB. In the preceding example, we define the type of destination destinationType and name JNDI of the destination used ( destination ). For that, we use an array of @ActivationConfigProperty specifying the name of the property propertyName and its value propertyValue .
Warning
The attribute mappedName is not to use because it is not portable between the various server of applications. It is possible to recover the context of the MDB with the injection (annotation @Resource ). The type of this object is MessageDrivenContext . We detail his use further. You can notice that the development of MDB is really simplified. Now ,we will study the various points of details of these components. MessageDrivenContext As the Beans Session, the Message Driven Beans also have a context of execution of the MessageDrivenContext type. It is similar to the SessionContext object explained in the part Session Bean. Indeed, this interface inherits EJBContext and does not add any method. Tolerance of the disconnection to a ?topic? The model of transport of the type ?subscription? obliges the client applications to be connected to the subject (topic) to receive the messages of this one. If a problem of connection occurs, the disconnected client lose the messages transmitted during their disconnection. However, as we had specified at the beginning of this chapter, the topic mode makes it possible to use a durable subscription. The interest is to be able to receive the messages transmitted since the last disconnection. The use of this kind of subscription must be specified on the level of the properties of the MDB. The property to be used is subscriptionDurability . The values taken by this one are: Durable or NonDurable . By default, a subscription is NonDurable .
@MessageDriven( activationConfig={ @ActivationConfigProperty(propertyName="subscriptionDurability",propertyValue="Durable") } )
Other properties exist and can be used ( subscriptionName , clientId ...). When the destination is of Queue type, the principle of durable subscription does not have any sence. By nature for this kind of destination, the ?durable? factor does not have importance because the messages are automatically stored and must be consumed by a single customer. Selector of message It is possible to specify certain criteria allowing not to receive the whole of the messages from a destination. The selector of message uses the properties of the message as a criterion in the conditional expressions. These conditions use Boolean expressions in order to determine the messages to receive. Here an example of use of these selectors of message.
@ActivationConfigProperty(propertyName="messageSelector",propertyValue="senderType='StockSenderCorp'")
These selectors are based on the properties of the messages. Those are located in the heading of the message, therefore depending of the contents, and are assigned by the creator of the message. All the types of message integrate the methods of reading and writing of properties. Indeed, these methods are described in the interface javax.jms.Message (superinterface defining a message). The types of properties are based on the Java primitives: boolean , int , shorts , char ... To define the values of the properties it is necessary to use the methods setXxxProperty(Xxx) where Xxx represent the types byte , float , String , Object ... The methods getXxxProperty() are also proposed to recover the values. In the following example, we define properties on which we will be able to define criteria of recovery.
TextMessage message = session.createTextMessage(); message.setText("Les indices boursiers Paris ont gagn 4% aujourd?hui") ; message.setIntProperty("result",4); message.setStringProperty("place","FR/Paris"); message.setStringProperty("senderType","StockSenderCorp");
Thanks to the properties which we have just defined, we can apply criteria of selection.
@MessageDriven(activationConfig={ activationConfig= { @ActivationConfigProperty( propertyName = "messageSelector", propertyValue = "place = 'FR/Paris' and result > 0")} }
Page 18 of 100

The system is based on the same concepts as the selection of the recordings with SQL. You can use operators AND, OR, <, >... Other functionalities are possible. Let us take the case where we wish to treat in a MDB all the messages having a relationship with the money markets Parisian, London, and francfortoise.
place IN ('FR/Paris', 'UK/London', 'GER/Francfort')
17/10/09 18:17
We can also think to an alarm system, if the one day result is not located between +10% and 10%, to warn the investor that this day is not an ordinary one.
result NOT BETWEEN 10 AND 10
Or treatment of the stock exchange places French or English

place LIKE 'FR/%' OR place LIKE 'UK/%'
This functionality is useful when we wish to sort and distribute the messages located in the same destination towards various MDB, in order to apply different treatments to them. Acknowledgement The disadvantage of the asynchronous treatment of messages is that there is no value of return to sender. It is difficult for him to know if the message were indeed transmitted (when it wishes to know, of course). There are various solutions to this problem. The first consists in using acknowledgements of delivery, transparent mechanism managed by the supplier and container MDB. It allow the client application to warn to the supplier that the message was received. Without this acknowledgement of delivery, the message will continue to be sent. This mechanism is based on the transactions on the level of the MDB. When this one is managed by the container, the acknowledgements just after the commit, or not if the transaction fails. There are two modes of acknowledgement: ?Autoacknowledge? and ?Dupsok acknowledge?. The mode ?Autoacknowledge? defines that the acknowledgement must be sent as soon as the message was transferred to the MDB.
@MessageDriven( name="MyQueue", mappedName = "queue/MyQueue", activationConfig={ @ActivationConfigProperty(propertyName="acknowledgeMode",propertyValue="Autoacknowledge") } ) @TransactionAttribute(TransactionAttributeType.NOT_SUPPORTED) public class MyTopicListener implements MessageListener { // ... }
For Dupsokacknowledge , the acknowledgement is pushed back at one unspecified moment and the container chooses then the moment when it has few tasks to treat to send it. That permit to save the resources. One can however disadvise this last value because the supplier could believe that the message was not treated and would decide to transmit it again (what could involve dysfunctions). Moreover, the cost of sending an acknowledgement of delivery is negligible that it is in capacity of calculation or load network.
@MessageDriven( name="MyQueue", mappedName = "queue/MyQueue", activationConfig={ @ActivationConfigProperty(propertyName="acknowledgeMode",propertyValue="Dupsokacknowledge") } ) @TransactionAttribute(TransactionAttributeType.NOT_SUPPORTED) public class MyTopicListener implements MessageListener { // ... }
The second solution consists in specifying the JMSReplyTo value in the parameters of heading of the message. That makes it possible to the recipient to send an answer towards the parameterized destination. As regards shipper, we define the destination of answer in the following way:
Destination replyDestination = context.lookup("queue/ReplyQueue"); message.setJMSReplyTo(replyDestination);
The MDB receiving the message can then recover this property and send in its turn a message.
Destination replyDestination = message.getReplyTo();
This method differs from preceding because it allows a real information feedback concerning the treatment of the message. This solution is typically used in our example of forwardings. The message of return alerts the system when the object is prepared and dispatched. That could not have been implemented with the first solution. This solution is also interesting to go up reports/ratios of errors in the business process. MDB and JMS client We directed our presentation MDB and JMS mainly towards the consumption of messages more than on the production of these messages. There exists however many evolutions facilitating the development of the sending of these messages. Let us point out the various steps for sends of a message JMS: Recovery of a ConnectionFactory object Recovery of the destination Opening of a connection Creation of a session Creation of a MessageProducer Creation of a Message
Page 19 of 100
17/10/09 18:17
Sending of the message Disconnection.

public class StockAlertListener { @Resource (mappedName = "ConnectionFactoryName") private ConnectionFactory cnxFactory; @Resource (mappedName = "queue/StockAlertQueue") private Queue stockAlertQueue; public void sendAlertMessage(String textAlert) { Connection cnx = cnxFactory.createConnection(); Session session = cnx.createSession(true, 0); MessageProducer producer = session.createProducer(stockAlertQueue); TextMessage message = session.createTextMessage(); message.setText(textAlert); producer.send(message); cnx.close(); } }
The first two steps of recovery are automated with the principle of injection. For that, we used the annotation @Resource which defines name JNDI of ConnectionFactory and the Destination (of Queue type, here). The code of the method sendAlertMessage (String textAlert) do not changes a lot compared to the implementation code client presented before.
Note
The examples presented in this part can completely be implemented within a Bean Session exactly in the same way. Life cycle Just like the Session Beans, a Message Driven Bean has a cycle of life managed by the container. This type of component has only two states: ?Does not exist? and ?ready Method?.
A MDB is in the state ?does not exist? when there is not any instance in memory of this one (it was not instanciate yet). A MDB is in the state ?Method ready? when the instance is ready to be used. Once the application started, the container creates a whole of instance of MDB of which the state is ?ready Method?. The following steps describe the changes of state which a MDB can undergo: The instance is created when the container calls the method newInstance() in the class of the component (generally with the starting of the application). Then, the container injects all the dependences of the object. These dependences gather the injections annotated with @Resource , @EJB ... then the container calls the methods annotated with @PostConstruct . The instance is now ready to treat the messages delivered with the listened destination: state ?ready Method?. When the container does not need more the instance, it calls the methods annotated with @PreDestroy . That generally occurs when the reserve of instances becomes disproportionate compared to the needs or that the application stops. The interest of the method declared with @PostConstruct is to open a connection towards a service, like the access to a directory of company or more simply to a file. The second method, @PreDestroy , are used to release the resources used.
private FileWriter fw = null; @PostConstruct private void connectToFile() { try { fw = new FileWriter(new File("save_topic.txt")) ; } catch(Exception e) { ... } } @PreDestroy private void unconnectToFile() { try { fw.close(); } catch(Exception e) { ... } } public void onMessage(Message message){ try{ //... fw.flush();
Page 20 of 100
17/10/09 18:17
} catch(IOException ex) { ex.printStackTrace(); } }
Notice that we forced the writing in the file at the end of the method onMessage() with FileWriter.flush(). The interest is to be sure that the file is written. Indeed, for certain reasons, the methods of recall can not be called and the data remained in memory can be lost.
Specification of Entity Bean

Class of Bean The Entity Bean class is the first element to be defined in EJB 3. Like known as previously, Entity Beans are POJO (Plain Old Java Objects ). So the creation of an Entity Bean User is summarized with the creation of an User class, such as we would do it in an application Java SE. The persistent state of the entity is represented by the variables of instance of the class which correspond to the properties of the POJO. These variables can be private, be protected or not specified. The client cannot reach directly the variables and must use the getter and setter or other methods trades of the class. This class must, however, comply with certain rules: This class can be abstract or concrete. The class can as well inherit a class entity as a class not entity, and conversely. The methods, the properties of the class and the class itself should not be final If an instance of the entity have the possibility of being sent to a distant client, then the class must implement java.io.Serializable. Indeed, RMI uses the (un)serialisation to pass the arguments between the client application and the client. The class must have a constructor without argument which can be public or protected. Nevertheless, the class can have overrided manufacturers if the preceding condition is observed.
Note
The goal of the default constructor (without argument) is to simplify the instanciation of the class by the container. The dynamic management of any constructor is a heavy task for this one without to be useful. The solution was to define a constructor common to all Entity Bean: the default constructor. EJB 3 Entity Beans support the heritage, associations and the polymorphic requests. These various concepts will be explained throughout this chapter.
@Entity public class User { //... }
It is with the annotation @Entity that the container will be able to know which classes must be consider as Entity Bean. This annotation is on the class and allow to define, the name of the entity with the attribute name . The name used must be unique in an application. The default value used is the name of the class (?User? in the preceding example). This name is used to represent the entity in the requests EJBQL, which we will see later; it is the abstract diagram of Entity Bean.
@Entity(name = "MyUser") public class User { //... }
Entity Bean is related to a table in database. This connection is called the mapping. By default, Entity Bean User is mapped on the table ?User?. If for certain reasons, you want to map on another table, you will have to use the annotation @Table. This annotation has various attributes:
name (required): defines the name of the table to use for the mapping. catalog (optional): define the catalogue used. diagram (optional): define the diagram used. uniqueConstraints (optional): defines the constraints which will be placed on the table. This attribute is used
when the container generates the tables with the deployment and of anything the execution even entity does not affect.
@Entity @Table(name = "XUser") public class User { //... }
Note
The name table ?User? is a reserved name in certain databases like PostGreSql, therefore we named it in the example above ?XUser?.
Persistent fields
A persistent field represents a property of Entity Bean. For an user entity, it will be for example: the name, the first name, the address, the date of birth, the sex... Any field (variable of instance) not ?static? and not ?transient?, of Entity Bean, is automatically considered as persistent by the container. A set of standard annotations is defined in EJB 3 specifications. We can consider two types of annotation related to Mapping Objet/Relationnel : annotations related to the properties
Page 21 of 100
17/10/09 18:17
annotations related to the columns These two types of annotations, which will be described in a more detailed way in the following parts, can be placed in two ways: Directly on a field On the getter and setter (more precisely on the getter)
Default Mapping
When you will create your bean, you will need to map the whole of your fields. However it is possible to use the default mapping. This mapping will be used when you do not use an annotation for a field (that it is persistent or relational), and that corresponds to the annotation @Basic . So it is to the manager of persistence selecting the suitable type of variable. The policy of API Persistence is to consider any property as a persistent field. That means that it is not necessary to annotate the properties to indicate them persistent. The container considers by default that the property is annotated with @Basic with the default values of the following attributes:
fetch ( FetchType.EAGER default) : determines whether the contents of the property must be in charge with the request 1 ( FetchType.LAZY ) or at the time of the loading of the entity ( FetchType.EAGER ). optional ( true default) : determines whether the property accepts or not the value " null ". This attribute does not function for the primitive types (which cannot be null ).
Other annotations allow to specify the parameter setting of the columns (in the relational table) related to the persistent properties. With those, it is then possible to specify type SQL, the length of the field, and many other properties to be used for a persistent property. The annotation @Column will be necessary to use to specify these parameter settings SQL. This one ?ondefine? default values declared by EJB 3 specification. This annotation can be used jointly with the preceding ones. Here a description of the attributes, all optional, annotation @Column :
name : specify the name of the dependent column. The name of the property is used by default. unique : specify if the property is a unique key or not (the value is unique in the table). nullable : specify if the column accepts null values or not. insertable : specify if the value must be included during the execution of request SQL INSERT. The default
value is true. is true.
updatable : specify if the value must be updated during the execution of request SQL UPDATE. The default value columnDefinition : specify the ?piece of code SQL? for the definition of the column in the database. It is with
this attribute that we can specify the SQL type of the column.
table : specify the table used to contain the column. The default value is the principal table of the entity. This
attribute is used when Entity Bean is maped with several tables.
length : specify the length that the data base must associate a field text. The length by defect is 255. scale : specify the fixed number of figures after the decimal separator (in general the point). This attribute is
usable only for the decimal properties (float, double...). The default number of decimal is defined by the database.
@Column(updatable = true, name = "price", nullable = false, precision=5, scale=2) public float getPrice() { return price; }
The many default settings of API Persistence offers an advantage to the developer. This one can quickly test its entities. However, it should not remain there, but use the possibilities exposed about it here to optimize the mapping between its entities and the database.
Primary Key
Entity Bean must have a field whose value is unique, known as primary key. This field allow to differentiate each instance from the entity of the others. This primary key must be defined only once in all the hierarchy of Entity Bean. There are two types of identifier: simple and composite. We explain, in this part the first case the second is more rarely used.
Simple Identifier
We speaks about simple identifier when this one is composed by a single field whose type is ?simple?. The simple types are: primitive types ( int , float , char ...), a wrapper (For example Integer , Float , Double ...), the String type or Date ( java.util.Date or java.sql.Date ).
Note
In general, the decimal ones (a number with comma) are not used as a primary key. The entities using this type for the primary key are likely not portable. To specify with the container that a field is a primary key, it is necessary to annotate this one with @Id . In our Entity Bean User , the primary key is assigned with the field id .
@Entity public class User implements Serializable { private int id; @Id @GeneratedValue(strategy = GenerationType.AUTO) // optionnel public int getId() { return id;
Page 22 of 100
17/10/09 18:17
} public void setId(int id) { this.id = id; } }
The last example uses the annotation @GeneratedValue which allow to indicate to the container to use the best solution for the generation of the primary key. There are four strategies of generation available: AUTO , IDENTITY , SEQUENCE and TABLE . Those are defined by the enumeration javax.persistence.GenerationType .
IDENTITY type indicates to the supplier persistence assigning the value of the primary key by using the column identity of the data base. Under MySQL, for example, the autogenerated primary key is marked with ? AUTO_INCREMENT ?. @Id @GeneratedValue(strategy = GenerationType.IDENTITY) public int getId() { /* ... */ }
The SEQUENCE type, as its name indicates it, obliges the supplier of persistence to use a sequence of the database. This one can be declared on the class or the package with @SequenceGenerator and its attributes:
name (require): a unique name for the sequence which can be referred by one or more classes (according to the
level used for the declaration of the annotation) the values of the dependent primary keys.
sequenceName (optional): defines the name of the sequence object of the database which will be used to recover initialValue (optional): the value which must start the sequence. allocationSize (optional): defines the number used for the incrementing of the sequence when the supplier of
persistence reaches it.
Warning
The default value for the attribute allocationSize is 50
@Entity @SequenceGenerator( name="SEQ_USER", sequenceName="SEQ_USER" ) public class User { private int id; @Id @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="SEQ_USER") public int getId() { return id; } }
This type of generation is useful when the database offers a native system of sequence and that it is advised to use it by the supplier of this one. The TABLE type indicates to the supplier persistence using an additional table to generate the numerical primary keys. This case of use is rarest.
@Entity @TableGenerator( name="CONTACT_GEN", table="GENERATOR_TABLE", pkColumnName = "key", valueColumnName = "hi", pkColumnValue="id", allocationSize=25 ) public class User { private int id; @Id @GeneratedValue(strategy=GenerationType.TABLE, generator="CONTACT_GEN") public int getId() { return id; } }
The annotation @TableGenerator allow to specify the parameters of creation of the additional table of generation. Here the detail of the attributes of this one:
name : a name for this definition of additional table table : the name of the table in the database pkColumnName : specify the name of the column which identifies the primary key for which the key is generated. valueColumnName : specify the name of the column which contains the meter of the primary key. allocationSize : the number of incrementings carried out when the supplier requests from the table a new
value. That allow to the supplier to use a system of cache in order not to require a new value of each request for new a id. The AUTO type indicates to the supplier persistence using the best strategy (between IDENTITY , TABLE , SEQUENCE ) according to the data base used. The generator AUTO is the type preferred to have a portable application. Even if the automatic incrementing of the primary key relieves the developer, it must be used with parsimony. Indeed, it is preferable to use a field of the entity rather than to add one of them, especially for the primary key. For example, the entity Account can contain a property accountNumber which wants to be single by banking logic. This property is then the best candidate for the primary key.
Simple Exemple
Page 23 of 100

Here an example of simple POJO. It allow to define the structure of table " COUNTRY ". It implements java.io.Serializable in order to be able to be sent directly to a distant client (and thus to pass through a network). The obligatory annotations are: @Entity which declares the class as being an entity @Id which declares the primary key (generate allow to define the type of generation to be used for this key. GeneratorType.AUTO defines a key incremented car). The other annotations are not obligatory allow to specify more precisely various parameters: @Table defines the name of the table to be used @Basic defines the type of a persistent field (by defect, this type is used)
@Entity @Table(name = "COUNTRY") public class Country implements Serializable { private int id; private String name; public Country() { } @Id(generate = GeneratorType.AUTO) @Basic public int getId() { return id; } public void setId(int id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } }
17/10/09 18:17
Relations We saw the definition of persistent property previously. It proves that an entity generally does not work only but that it is connected to other entities. We speak then about relations between entities. To define a relational field within an entity, it is enough to create a property whose type is an entity (cardinality 1) or a whole of entity (cardinality N). A relation is known as oneway if only one part knows the relation. On the other hand, it is described as bidirectional if the two parts know it. For the relations where one side, at least, is multivalued ("One to Many", "Many to One", "Many to Many"), the types of containers available are: java.util.Collection , java.util.Set , java.util.List , and java.util.Map . They are these relations between entity EJB 3 which we detail in the next parts. One to One A relation "One to One" is used to bind two indissociable uniques entities. For example, a body has one heart, or a person has only one indentity card. We will suppose, in our example, which a user User has one AccountInfo account. To associate two entities with this type of relation, the annotation @OneToOne should be used. This one takes again the attributes of @Basic , considering previously, and proposes other optional attributes:
cascade : specify the operations to be carried out in cascade. mappedBy : specify the field owner of the relation the case of a bidirectional relation. targetEntity : specify the class of a target entity. This attribute is not used a lot because the annotation uses
the type of the property automatically.
This type of relation can be mapped with 3 manners in the database. The first solution consists in using the same values for the primary keys of the two entities. It is then necessary to specify this choice via the annotation @PrimaryKeyJoinColumn (joint by primary key). Here the example of the oneway relation between User and AccountInfo with this method.
@Entity public class AccountInfo { private int id; private String cardNumber; private double amount; private String accountId; @Id @GeneratedValue(strategy=GenerationType.AUTO) public int getId() { return id; } public void setId(int id) {
Page 24 of 100
17/10/09 18:17
this.id = id; } public String getCardNumber() { return cardNumber; } public void setCardNumber(String cardNumber) { this.cardNumber = cardNumber; } // Others getters and setters } @Entity public class User { // ... @OneToOne @PrimaryKeyJoinColumn public AccountInfo getAccountInfo() { return accountInfo; } // .... }
The second solution consists in using a foreign key on a side of the relation. However, it should be noted that the column of this key must be marked like single in order to simulating correctly the relation ?One to One?. The annotation to use is @JoinColumn. It makes it possible to parameterize the column of joint to be used. The example shows the bidirectional relation.
@Entity public class User { // ... @OneToOne @JoinColumn(name="account_id", referencedColumnName="id") public AccountInfo getAccountInfo() { return accountInfo; } // ... }
The annotation @JoinColumn resembles @Column but has an optional additional attribute: referencedColumnName . This one makes it possible to specify the name of the column referred by the foreign key of association.
@Entity public class AccountInfo { // ... private int id; private User user; @OneToOne(mappedBy = "accountInfo") public User getUser() { return user; } // ... }
The attribute mappedBy declares that the side owner is that holding the property accountInfo . It is thus, here, the User entity which holds the relation and thus has the capacity to bind a user on an account (the reverse being impossible). The last solution consists in using a table of association of the links between the two entities. However, the multiplicity ? One to One? is respected if and only if one unique constraint is defined on each foreign key. Even if this case is rarer, it is possible to find it in an existing system which one wishes to make evolve.
@Entity public class User { // ... @OneToOne @JoinTable(name = "UserAccountInfo" joinColumns = @JoinColumn(name="user_fk", unique=true), inverseJoinColumns = @JoinColumns(name="accountinfo_fk", unique=true) ) public AccountInfo getAccountInfo() { // ... } } @Entity public class AccountInfo { //... @OneToOne(mappedBy = "accountInfo") public User getUser() {
Page 25 of 100
17/10/09 18:17
// ... } }
This technique obliges to write more lines, without to increase the performances. It is however a considerable case when we use of an existing data source. The annotation @JoinTable allow to configure the table of joint for relation. Here a description of the attributes of this one:
name : specify the name of the joint table catalog : specify the catalogue of the joint table schema : specify the diagram of the joint table joinColumns : specify the columns (together @JoinColumn) of the join table which refer the primary keys of the
entity owner of the relation (side owner).
inverseJoinColumns : specify the columns (together @JoinColumn ) of the joint table which refer the primary
key(s) of the entity not owner (opposite side). generation of the table is activated.
uniqueConstraints : specify the unique constraints to place in the table. This attribute is used only if the
In the absence of any parameter of the annotation @OneToOne , the link between the two entities will be made with a column of joint (second solution) in the owner entity. The name of this one will be the result of the concatenation of the name of the relational property with the name of the primary key of the other entity. Concretely, in the example used previously, the owner entity User definite the named persistent property accountInfo ; the primary key of AccountInfo being id , the name would be accountInfo_id . One To Many and Many To One A relation ?One To Many?, and respectively ?Many To One?, is used to bind to a unique instance of an entity A, a group of authorities of an entity B. For example, a person has several bank accounts, but a bank account belongs only to only one person. In our following examples, a user can have several wallets of actions, but a wallet is dependent only on one user. An association ?Many To One? is defined on a property with the annotation @ManyToOne . In the case of a bidirectional relation, the other side must use the annotation @OneToMany . The attributes of these two annotations correspond to those of the annotation @OneToOne .
@Entity public class Portfolio { //... private User user; @ManyToOne @JoinColumn(name = "user_fk") public User getUser() { return user; } public void setUser(User user) { this.user = user; } } @Entity public class User implements Serializable { //... private Collection<Portfolio> portfolios; @OneToMany(mappedBy = "user") public Collection<Portfolio> getPortfolios() { return portfolios; } public void setPortfolios(Collection<Portfolio> portfolios) { this.portfolios = portfolios; } }
The entity Portfolio , being the part of the relation having a cardinality of 1, defines a User property user . On the other hand, the entity User , part of the relation to cardinality ?N?, declare a property multivalued Collection<Portfolio> portfolios . Notice the use of the credits which avoid defining the target entity in the definition of our relation. If you do not wish to use them, then you will have to specify the target of your relation with the attribute targetEntity of the annotation @OneToMany . In the same way that with a relation ?One to One?, it is possible to use a table of association. The way of proceeding already having been explained previously, we will not return above. Many To Many The last type of relation available is ?Many to Many?. It can be used to bind instances of two entities between them. For example, between articles and categories. An article can be associated several categories (cardinality N) and a category can gather several articles (cardinality m). For that, it is enough to use multivalued properties on each side of the relation (if this one is bidirectional) and to annotate them with @ManyToMany . In relational term, this relation imposes the use of a table of association.
@Entity public class User {
Page 26 of 100
17/10/09 18:17
//... private Collection<Hobby> hobbies; @ManyToMany @JoinTable(name = "USER_HOBBIES", joinColumns = @JoinColumn(name = "user_id", referencedColumnName = "id"), inverseJoinColumns = @JoinColumn(name = "hobby_id", referencedColumnName = "id") ) public Collection<Hobby> getHobbies() { return hobbies; } public void setHobbies(Collection<Hobby> hobbies) { this.hobbies = hobbies; } } @Entity public class Hobby { //... private Collection<User> users; @ManyToMany(mappedBy="hobbies") public Collection<User> getUsers() { return users; } public void setUsers(Collection<User> users) { this.users = users; } }
Here, each User user has a whole of hobbies Hobby. And conversely, each hobby Hobby can be related to several User users. Cascading operations The annotations @OneToOne , @OneToMany , @ManyToOne and @ManyToMany have the attribute cascade . This one specifies the operations to be carried out in cascade. The cascade means that operation applied to an entity is propagated with the relations of this one. For example, when a user is removed, its account is also. There are 4 possible operations on the entities: addition, modification, suppression, reloading. These operations are gathered in the CascadeType enumeration.
CascadeType.PERSIST : automate the recording of the entities related to the association marked during the recording of the entity owner (method persist() ). CascadeType.MERGE : automate the recording of the modifications of the entities related to marked association, during the recording of the modifications of the entity owner (method merge() ). CascadeType.REMOVE : automate the suppression of the entities related to marked association, during the suppression of the entity owner (method remove() ). CascadeType.REFRESH : automate recharging (side bases data) entities related to marked association, during the recharging of the entity owner (method refresh() ). CascadeType.ALL : cumulate the 4 types of cascade.
Warning
According to the specification, the CascadeType.REMOVE type can be applied only to associations "One to One" or "One to Many". The use of this type for other associations is not portable. For example, on the relation between User and Portfolio, it is logical to record or remove the wallets when the user is respectively recorded or removed. Here the code corresponding:
@OneToMany( cascade = { CascadeType.REMOVE, CascadeType.PERSIST }, mappedBy = "user" ) public Collection<Portfolio> getPortfolios() { return portfolios; }
In the same way, the relation ?One to One? between User and AccountInfo obliges to safeguard, update and destroy AccountInfo when these operations are carried out on the instanct of User corresponding. Here the code corresponding:
@OneToOne(cascade = CascadeType.ALL) @PrimaryKeyJoinColumn public AccountInfo getAccountInfo() { return accountInfo; }
The use of the mechanism of cascade is a real simplification for the developer. Indeed, it does not have to manage the loops of suppression any more, modification... However, this tool must be used judiciously and with parsimony. Indeed, a too important use of this mechanism can very quickly harm the performances of the application.
Relationnal sample
This bean integrates a relation with another bean of the type: ManyToOne. This relation highlights a field of the Country type. The use of the relational annotations describes more in detail the relation:
@ManyToOne defines the type of the relation (ManyToOne) @JoinColumn defines the column of joint for this relation
Page 27 of 100
17/10/09 18:17
package com.society.stockmanager3.entities.beans; import import import import import import import java.io.Serializable; javax.persistence.Entity; javax.persistence.GeneratorType; javax.persistence.Id; javax.persistence.JoinColumn; javax.persistence.ManyToOne; javax.persistence.Table;
@Entity @Table(name = "CITY") public class City implements Serializable { protected int id; protected String name; protected Country country; public City() { } public City(String name) { this.name = name; } @Id(generate = GeneratorType.AUTO) public int getId() { return id; } public void setId(int id) { this.id = id; } @ManyToOne(optional = false) @JoinColumn(name = "countryId") public Country getCountry() { return country; } public void setCountry(Country country) { this.country = country; } public String getName() { return name; } public void setName(String name) { this.name = name; } }
One Many to Many or two One to Many ? A relation ?Many to Many? is the regrouping of two relations ?One to Many?. Indeed, the relation ?Many to Many? uses a simple table of joint containing the primary keys on the two sides of the relation. What happen if we wish to add properties to this relation? For example, when an order gathers products, those can also be used in several orders. We then find ourselves in the case of a relation ?Many to Many?. However, it is generally useful to add a property concerning, for example, the quantity of the desired product. The use of the annotation @ManyToMany does not allow the insertion of additional properties the relation between the two objects. It is then necessary to use a double connection ?One to Many? and intermediate Entity Bean. In our example, we have Entity Bean following: Order , Product and OrderLine , respectively representing an order, a product and the lines of the orders. Here respective codes:
@Entity @Table(name="ORDERS") public class Order { private int id; private Date orderDate; private Collection<OrderLine> orderLines; @Id @GeneratedValue(strategy=GenerationType.AUTO) public int getId() { return id; } public void setId(int id) { this.id = id; } public Date getOrderDate() { return orderDate; } public void setOrderDate(Date orderDate) { this.orderDate = orderDate; } @OneToMany(mappedBy = "order", cascade = {CascadeType.REMOVE}) public Collection<OrderLine> getOrderLines() { return orderLines; }
Page 28 of 100
17/10/09 18:17
public void setOrderLines(Collection<OrderLine> ol) { this.orderLines = ol; } } @Entity public class Product { private int id; private String name; @Id @GeneratedValue(strategy=GenerationType.AUTO) public int getId() { return id; } public void setId(int id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } }
The classes Order and Product are Entity Bean as we could describe them in the first parts. Entity Bean OrderLine is the central point of the relation. It gets the two properties product and order respectively related to Entity Bean Product and Order . Moreover, if an autogenerated unique primary key would simplify the work of the developer, it is more judicious to work with a composite primary key. Indeed, the regrouping of the primary keys of Product and Order are a good candidate for a primary key, since an order cannot have the same product twice (in this case there it is enough to increment the quantity). We must then create a OrderLinePk class to define this composite primary key. This one contains two properties orderId and productId respectively representing the id of Order and Product . The annotation @Embeddable declared below makes it possible to declare an entity in time that key composite primary education.
@Embeddable public class OrderLinePk implements Serializable { private static final long serialVersionUID = 1L; private int orderId; private int productId; protected OrderLinePk() { } public OrderLinePk(int orderId, int productId) { this.orderId = orderId; this.productId = productId; } public int getOrderId() { return orderId; } public void setOrderId(int orderId) { this.orderId = orderId; } public int getProductId() { return productId; } public void setProductId(int productId) { this.productId = productId; } public int hashCode() { return orderId ^ productId; } public boolean equals(Object that) { return (that instanceOf OrderLinkPk && orderId == productId); } }
Why we use the methods hashCode() and equals() above? They are used for calculter a value based on the contents of the instance and to compare this one with others.
@Entity @IdClass(OrderLinePk.class) public class OrderLine { private Product product; private Order order; private int quantity;
Page 29 of 100
17/10/09 18:17
public OrderLine() { } public int getQuantity() { return quantity; } public void setQuantity(int quantity) { this.quantity = quantity; } @ManyToOne @JoinColumn(name="orderId", optional=false, insertable=false, updatable=false ) public Order getOrder() { return order; } public void setOrder(Order order) { this.order = order; } @ManyToOne @JoinColumn(name="productId", optional=false, insertable=false, updatable=false ) public Product getProduct() { return product; } public void setProduct(Product product) { this.product = product; } @Id public int getProductId() { return getProduct().getId(); } @Id public int getOrderId() { return getOrder().getId(); } public void setOrderId(int orderId) { getOrder().setId(orderId); } public void setProductId(int productId) { getProduct().setId(productId); } }
We use the annotation @IdClass in order to specify the class of the primary key used. The getters getProductId() and getOrderId() ondefine those of the OrderLinePk class. However, they respectively turn over the primary key of the dependent order Order and that of the dependent product Product . That raises a problem: the columns orderId and productId are already used to refer in the relations Many to One. They are used at the same time as primary key and foreign key! The supplier of entities encounters a problem: to assign the primary key and the foreign keys. To specify that we do not wish to assign the foreign keys automatically, it is necessary to assign the value false to the attributes insertable and updatable of the annotation @JoinColumn . The heritage Here 3 possible relational types of mappings: A single table by hierarchy of class. A table by concrete class. A separation of the specific fields of a class girl in a separate table of the table relationship. A junction is then made for instancier the class girl. The examples of this part will use two Entity Bean: Bond and Stock which inherit both Entity Bean FinancialProduct (abstract class).
Warning
Only one primary key must be defined in a hierarchy. Here, the primary key is in the root class FinancialProduct .
Page 30 of 100
17/10/09 18:17
We will describe the possibilities of each one of these configurations, like their advantages and disadvantages. The goal is to give you the elements enabling you to make the best choice according to various situations'. For each case, we will study the annotations used and the generated relational structure.
A table for a hierarchie of class
In this strategy, all the classes of the hierarchy are mapped in same and unique table. The type of heritage used is specified on the level of root Entity Bean by the annotation @Inheritance .
@Entity @Inheritance(strategy=InheritanceType.SINGLE_TABLE) @DiscriminatorColumn( name="financialproduct_type", discriminatorType=DiscriminatorType.STRING, length=10 ) public abstract class FinancialProduct { private int id; //... @Id @GeneratedValue(strategy=GeneratorType.AUTO) public int getId(){ return id; } //... }
The only attribute of this annotation is strategy . It allow to specify the type of strategy to use with the InheritanceType enumeration. To define a heritage using the strategy "unique table", it is the value InheritanceType.SINGLE_TABLE which will be used. However, this strategy requires a column allowing to differentiate the types of entity of the hierarchy. It is necessary to use the annotation @DiscriminatorColumn to specify the details of this column. The attributes of this annotation are:
name : name of the column of discrimination discriminatorType : discriminator class to be used defined by the enumeration. Possible values are INTEGER , CHAR and STRING . length : size of the column for the discriminator at the root of the string. columnDefinition : SQL fragment to be used for the declaration of the column (used during the generation of
the tables by the container).
The concrete children classes can specify the discriminatory value with the annotation @DiscriminatorValue . The default value of a discriminator of the type STRING contains the name of the class of Entity Bean. Thus, the contents of the discriminatory column contain ?Bond? if the stored EntityBean is of Bond type, and ?Stock? if its type is Stock . For the other types of discriminator, the supplier uses a specific method to generate automatically a value for Entity Bean.
@Entity @DiscriminatorValue("BOND") // valeur par dfaut public class Bond extends FinancialProduct { private double rate; // taux de rendement de l?obligation
private int monthDuration; // nombre de mois que dure l?obligation //... @Basic public double getRate(){ return rate; } @Basic public int getMonthDuration(){ return monthDuration; } //... } @Entity @DiscriminatorValue("STOCKOPTION") public class Stock extends FinancialProduct { // ... }
Here the result at the database level (one table for two entities):
This strategy provides an important profit of performance, because no joint is carried out. However, the data use more place because the whole of the columns is not always used (according to the type of recorded data). Here, rate has a
Page 31 of 100

value ?null? when the recording corresponds to a Stock Entity Bean.
One table by concrete class
17/10/09 18:17
The second strategy presented here is ?one table by concrete class?. In this case, each concrete class Entity Bean is related to its own table. That means that all the properties of the class (including the inherited properties) are included in the table related to this entity. Concretely, on our example, that means that the table ? FinancialProduct ? is not created nor not used. Entity Bean Stock and Bond which inherit the FinancialProduct class are mapped respectively on the tables ? Stock ? and ? Jump ?; each one of these tables integrating the properties defined in FinancialProduct . To specify this strategy, it is necessary to specify the strategy defined by InheritanceType.TABLE_PER_CLASS for the annotation @Inheritance .
@Entity @Inheritance (strategy=InheritanceType.TABLE_PER_CLASS) public abstract class FinancialProduct { //... }
The children classes Bond and Stock have simply to inherit FinancialProduct .
@Entity public class Stock extends FinancialProduct { //... }
Here is the result in the database:
The major advantage of this configuration is during insertion because the addition is made only in one table. In the same way, the selection of a concrete type (here Bond or Stock ) is optimized. Indeed, SELECT relates to only one table. The main disadvantage is the heaviness of the polymorphic requests (selection on the whole of FinancialProduct, for example). Indeed, the data base must use instruction SQL ?UNION? in order to gather the recordings located in the two tables. The other disadvantage is the duplication of the columns in each table of Entity Bean; DataBase Administrators never appreciate this kind of practice.
One table for a specific part of data
In this last strategy, the class root of the entities is represented by a table. Each children class is related to its own separate table containing the specific properties of that one. The link between the tables ?child? and the table root is made with the primary keys. Indeed, the primary key of the class girl is related to that of the class relationship. Thus, a recording of the table ?Stock? or ?Bond? whose value of the primary key is 15, is related to a recording of the table ?FinancialProduct? having value 15 for the primary key. The heritage is declared here with the InheritanceType.JOINED strategy.
@Entity @Inheritance (strategy=InheritanceType.JOINED) public class FinancialProduct { //... }
The children classes Bond and Stock do not need another annotation only @Entity :
@Entity public class Bond extends FinancialProduct { //... } @Entity public class Stock extends FinancialProduct { //... }
Here the result at the database level (place optimization tacken by the data):
Page 32 of 100
17/10/09 18:17
The advantage of this strategy is to have a clearly relational model. It is the ideal model for the dBa (not of loss of memory because all the fields are used,...). But is also to provide a good support of polymorphism. Thus, when the client wishes to recover all Entity Beans of the FinancialProduct type, generated request SQL will result in a simple ? SELECT * FROM FinancialProduct... ?. However, the disadvantage is that it requires the use of several joints between the tables during recovery of data. In the case of important hierarchies (great depth of the heritage) that can involve bad performances.
Warning
Toplink, the GlassFish presistence provider, doesn't supports the joined inheritance type.
Summary of the methods of mapping of the heritage
Here a summary of the advantages an disadvantages of the differents strategies: Table 6. Advantages and disadvantages of the differents mapping strategies Strategy Advantages Disadvantages SINGLE_TABLE No joint, therefore very powerful Nonoptimal organization of the data TABLE_PER_CLASS Powerful in insertion Heavy polymorphism to manage JOINED Integration of the data close to the model object Intensive use of the joints, therefore lowers performance
Persistence unit
The persistence unit is a device making it possible to establish a link between Entity Beans and the database Configuration of a persistance unit The specification defines a file which gathers the whole of information of persistence. You must name this file: ? persistence.xml? and to place this file in repertory ?META INF?, to the root of the project. This file will be read by EJB container during the deployment of the application. The container then creates an instance of the supplier of persistence with the required parameters.
Warning
You must name correctly the file ?persistence.xml?. If the name does not match, the container will not associate any context of persistence in the application. Here the file ?persistence.xml?, parameterized with Hibernate, used in our example:
<?xml version="1.0"?> <persistence version="1.0"> <persistenceunit name="stockmanagerUP"> <jtadatasource>java:StockMainDS</jtadatasource> <provider>org.hibernate.ejb.HibernatePersistence</provider> <properties> <property name="hibernate.hbm2ddl.auto" value="createdrop" /> <property name="hibernate.dialect" value="org.hibernate.dialect.MySQLInnoDBDialect" /> </properties> </persistenceunit> </persistence>
Here a description of each mark used:

<persistenceunit> (0N) : declare a unit of persistence
The attribute name assigns a unique name to this unit in your application. The name is used to identify the unit of persistence during its use with the annotations You will have to define several units of persistence if you wish to use several data sources.
<jtadatasource> (01) : allows to define name JNDI for the data source to use. This one must be parameterized
on the server and integrate the Transactions.
<provider> (01) : allows to define the class of implementation of the supplier of persistence used in the
application (subclass of javax.persistence.spi.PersistenceProvider). Each unit of persistence uses a unqiue supplier. You can, in environment Java EE, use the default supplier of the server of application: JBoss uses Hibernate: org.hibernate.ejb.HibernatePersistence Oracle Application Server uses TopLink: oracle.toplink.essentials.ejb.cm p3.EntityManagerFactoryProvider GlassFish (Sun Application Server 9) uses TopLink: oracle.toplink.essentials.ejb.cm p3.EntityManagerFactoryProvider KODO: kodo.persistence.PersistenceProviderImpl
Page 33 of 100

<properties> (0N) : This mark allow you to configure the attributes of configuration of the supplier of
17/10/09 18:17
persistence. This mark gathers the whole of the properties <property>.
A <property> is defined by a name (attribute name ) and a value (attribute value ). A unit of persistence is mapped with a whole of Entity Bean. In a default environment Java EE, the container analyze the whole of the classes of the JAR file containing the file ?persistence.xml?. Like theses units of persistence use Hibernate, we can parameterize the engine of persistence with the properties available (related to Hibernate). We must specify the property hibernate.hbm2ddl.auto with the value update . This one allow automatically to generate the diagram of the database but also to update it in the event of modification of the structure of Entity Bean. The diagram will be generated according to the annotations read in the classes of entities. The property hibernate.dialect parameter the dialect used by Hibernate to communicate with the data base (here MySQL). There are some for the majority of the databases available, as one can see it in the package org.hibernate.dialect : Table 7. List of majors dialects proposed by Hibernate Database PostGreSQL Oracle SQL Server HSQLDB Derby DB2 Class of dialect org.hibernate.dialect.PostgreSQLDialect org.hibernate.dialect.OracleDialect org.hibernate.dialect.SQLServerDialect org.hibernate.dialect.HSQLDialect org.hibernate.dialect.DerbyDialect org.hibernate.dialect.DB2Dialect
MySQL (Inno DB) org.hibernate.dialect.MySQLInnoDBDialect
Persistence manager
We will describe, in this part, the use of API EntityManager in order to manage the cycle of life of an instance of Entity Bean.
Note
The access to the data is represented by the operations of addition, reading, modification and suppression (defined by acronym CRUD: Create Read Update Delete). We generally implements Pattern DAO to standardize these accesses In the majority of the cases, the handling of the data with a container EJB is carried out by defining a Bean Session in "facade".
Note
The design pattern "facade" provides a uniform interface of access to a whole of subsystems. The application uses a whole of systems without really being aware of it and having the difficulties of use which each system can induce. This Beans Session reaches the context of persistence and can then work with the instances of Entity Beans, with Entity Manager. It is what will be presented in the examples of the following parts. Recovery of Entity Manager It is possible to let the container give the responsability to inject an instance of Entity Manager at the time of instanciation of the Bean Session. This method is undoubtedly simplest and most practical. You must annotate the variable of instance of the type EntityManagerFactory or EntityManager with @PersistenceContext. This annotation admits several attributes:
name : declare a name local referred on a unit of deployed persistence (local reference towards a unit of
persistence).
unitName : the name of the unit of persistence defines to use to inject EntityManager.
type : indicate the context type of persistence injected ( EXTENDED or TRANSACTION ).
Here an example of use within the business application of wallet of actions. Here, EntityManagerFactory , related to the unit of named persistence stockmanagerUP , is injected.
@Stateless @Local({CommonService.class}) public class CommonServiceBean implements CommonService { @PersistenceContext(unitName="stockmanagerUP") protected EntityManagerFactory emStockManagerFactory; }
The context of persistence is created at the same time as the Bean Session and has the same cycle of life as this one. It is closed when the Bean Session is destroyed. During all the life of the Bean Session, the instance of Entity Beans associated with the context of persistence are managed. Persist an entity instance To record an entity mean to insert it in the database. This operation results in the call of the method EntityManager.persist(Object o) . This one does not apply that to entities yet not recorded in the database.
Page 34 of 100
17/10/09 18:17
To record an entity, you must first of all create an instance, then to affect its properties and its relationships to the desired values, as you can do it with a Java object. Finally, it is enough to call you the method persist() .
User newUser = new User(); newUser.setFirstname("Cyril"); newUser.setEmail("popom@supinfo.com"); entityManager.persist(newUser);
Once this method called, the instance newUser becomes managed and its insertion in database is put in the queue of Entity Manager. If the method persist() is called in a transaction, insertion in data base can be immediately made or put in queue until the transaction finishes. That depends on the mode used for synchronization at the data base. It is not possible to call the method persist() apart from a transaction only if Entity Manager is of wide type ( EXTENDED ). We will not have time to describe this operating mode more. Recovery entities Once the objects are saved, it is important to be able to recover them. There are two ways of recovering these objects of the database. We will detail the recovery of objects starting from their primary key. The other solution consists in working with requests EJBQL (see the following chapter). Entity Manager proposes the following method:
<T> T find(Class<T> entity, Object primaryKey)
The use of the generics avoids having to cast the return value. However differences exist. The method find() return null if no entity is associated with the required primary key. It also initializes the basic states of the lazyloading associated the properties.
User user1 = entityManager.find(User.class, 1); if (user1 == null) { // ... }
Modify entities There are two ways of modifying an entity. Either to load it from the database and the modifications within the transaction or you apply you to him wish to update a detached object and in this case there you must use the method merge() . When you recover an entity with find() or with a request, this one become managed until the closing of the context of persistence. You can then change the properties of this instance, the modifications will be synchronized automatically.
public void changeUserEmail(int userId, String email) { User currentUser = entityManager.find(User.class, userId); currentUser.setEmail(email); }
In the preceding example, Entity Manager must be associated to the current transaction if it is wished that the modifications be recorded. Those are really affected in database when the transaction finishes or that the method flush() is called explicitly.
The other solution is to use when you wish to amalgamate the modifications made on an object detached towards the context of persistence. It is the case, for example, when an entity leaves container EJB towards another application (Web or rich Customer). You must use the method EntityManager.merge() in order to attach the instance to the context of persistence. Let us imagine that a rich client calls the method findUser() following:
@PersistenceContext private EntityManager em; public User findUser(int userId) { return em.find(User.class, userId); }
The context of persistence is closed after the execution of the method findUser() (we suppose that the Bean Session uses management of the transactions). From there, returned instance is detached and the modifications applied are not synchronized any more. If the customer application wishes to record the modifications made locally, it must return the authority to the Bean Session.
User returnedUser = adminService.findUser(2);
Page 35 of 100
17/10/09 18:17
returnedUser.setEmail("nouvelleemail@supinfo.com"); adminService.updateUser(returnedUser);
In this case there, the method updateUser() must use EntityManager.merge() in order to attach the instance to the context.
@PersistenceContext private EntityManager em; public void updateUser(User user) { User attachedUser = em.merge(user); }
Various behaviors apply according to the context in which you call the method merge() . If Entity Manager does not contain an instance of the entity with the same primary key, then it creates a complete copy of the object passed in argument and return it. This copy is then attached to the context of persistence and the modifications made above are synchronized with the data base. If Entity Manager holds already an instance of the entity having the same primary key, then the contents of the parameter (user here) are copied in the attached instance. In both cases, the parameter user of the method updateUser() remains detached and is not synchronized with the database. This is why the developer must work with the instance turned over by the method merge() if it must make other modifications on the entity. Delete an instance The EntityManager.remove() method is used to ask for the suppression of an entity of the database. We speak about "request" because the suppression is not effective immediately but only with the call of the method flush() or at the closing of the context of persistence. Meanwhile, it is possible to cancel the suppression.
@PersistenceContext private EntityManager em; public void removeUser(int userId) { User userToRemove = em.find(userId); em.remove(userToRemove); }
The call to the method remove() detaches the entity of the context of persistence. To cancel this suppression (in the same context of persistence) it is necessary to call the method persist() in order to attach the instance to the context. Reload entities If you know that the instance of an entity does not reflect the values of the database , you can use the method EntityManager.refresh() in order to reload the entity since the data base. This operation override all the modifications which could be made to the entity.
@PersistenceContext private EntityManager em; public void workOnUser(int userId) { User user = em.find(userId); user.setEmail("nomail@supinfo.com"); em.refresh(user); }
In the last example, the email is not modified because of the call to the method refresh() . Synchronization with database When you call the methods persist() , merge() or remove() , the changes are not synchronized immediately. This synchronization is established automatically at the end of a transaction or when Entity Manager decides to empty its queue. However, the developer can force synchronization by explicitly calling the method flush() of Entity Manager.
Warning
flush() and commit() are two different operations! flush() sends requests SQL to the data sources whereas commit() validates the transaction on the level of these sources.
Management of the cycle of life of an entity

The cycle of life of an instance of Entity Bean includes 4 distinct states which it is necessary to know and understand. Here a description of these various states: ?new? : mean that the instance isn?t associated to a persistent context. This state results from the instanciation of Entity Bean with new. ?managed? : mean that the instance has an identity associated with the persistent context. An instance is generally in this state when it comes to be recorded, modified or to be recovered. ?detached? : mean that the instance is not associated any more with the persistent context from where it comes. It is generally the case when the instance is initialized in the container then sent to another third (presentation, Web...).
Page 36 of 100

?removed? : mean that the instance has an identity associated with a persistent context but which it is intended to be withdrawn from the data base.
17/10/09 18:17
The call of the methods related to the cycle of life is carried out by the container. We speaksabout callback methods (methods of return). However, the study of these methods would leave of the framework of this essence. Detached entities It is necessary to handle carefully the persistent fields marked by ?fetch=LAZY? when Entity Bean is handled apart from the context of persistence. Indeed, the marked collections ?lazy? are not charged by the container. But, in the case of a detached entity, if the collection were not charged in the container with EJB, it will be impossible to reach the property apart from the container To resolve that, we should be sure that all the properties of the entity used at the customer are initialized before the object is detached from the context of persistence. For that, it is enough to ask the loading of the data when the entity is still managed.
User user = entityManager.find(User.class, userId); user.getPortfolios().size(); user.getCVContent();
In this example, the loading of the collection is launched at the same time than the call to the method size() of this one. In the same way, the loading of the property cvContent is carried out at the same time than the access to this one.
Warning
The dynamic loading functions only on one managed entity ! Another solution consists in using requests EJBQL with explicit joints to recover the already initialized entities. For that, it is necessary to use key word FETCH JOIN in the request (see the following chapter).
EJB-QL
What EJBQL?
EJBQL (Undertaken JavaBean Query Language) is a specification of query language. Integrated into system EJB, this query language has several advantages. First of all, it?s the portability which enables him to be used with identical between the various versions of language SQL. Indeed, this one rests on an abstraction of language SQL and is translated into ?true? SQL at the time of its execution. In addition, EJBQL makes it possible to use the objects of Entity Beans of the application directly in the requests, for more facility. In the same way, the supplier of persistence will translate these requests into ?true? SQL at the time of the execution. The finality of this language is to some extent identical to that of the manager of persistence, which offers, indeed, the possibility of carrying out requests of the INSERT type, UPDATE or DELETE.
The abstract diagram

In order to work with the entities, EJBQL is based on the abstract diagram of Entity Bean. The abstract diagram is an internal representation of the entities and their relations. However, even if this term seems complex at first sight, one usually assimilates it in the name of Entity Bean. With specification EJB 3, one generally uses the annotations. One can then specify the name of reference by the attribute name of the annotation @Entity .
@Entity(name = "AccountInfo") public class AccountInfo { // ... }
By defect, the name of the class of Entity Bean will be used. For example, the diagram abstracted owing to lack of Entity Bean, defined by the class To use, is ?To use?. The abstract term distinguishes this diagram from the physical diagram of the data base. In a relational data base, the physical diagram corresponds to the structure of the tables and columns. In EJBQL you work with the abstract diagrams and not with the name of the tables of your physical diagram, as represents it the following diagram.
Page 37 of 100
17/10/09 18:17
Note
We advise you to draw a sketch of the diagram abstracted before writing your requests.
In short, it should be retained that it acts of an abstract representation of Entity Bean, used by EJBQL to sail between the persistent and relational properties.
Writing of requests
Before returning in the innumerable details of this language, here a first simple example which will enable you to more easily include/understand the continuation of the explanations.
String queryString = "SELECT user FROM User AS user"; Query query = entityManager.createQuery(queryString); List<User > allUsers = query.resultList(); for (User U: allUsers) { // Work on the user... }
The preceding example uses three different concepts: Language EJB-QL Entity manager API Query This one turns over the whole of the authorities of Entity Bean User in a list. This one can then be traversed by a foreach. The details of use of these elements are explained throughout this part. According to the salesmen, it is possible to journalize (?logs?) requests SQL carried out by the manager of persistence. For example, it is enough to add the property ?hibernate.show_sql? with the value ?true? if you use the engine of Hibernate persistence. We will try to the maximum to illustrate the requests of example with their correspondence SQL.
Warning
Correspondence SQL was carried out starting from tests carried out with the supplier Hibernate and a data base MySQL.
Fundamental of the language

A request EJBQL can fill a task of selection (SELECT), modification (UPDATE) or suppression (DELETE). A request EJBQL is similar with SQL, with the following clauses: SELECT: list Entity Beans and the properties turned over by the request. FROM: Entity Beans defines used. Those must be declared via the expression HAVE. WHERE: allows to apply search criteria. It is possible to specify Java types as well there having their equivalent in the data bases (String, Integer, Double...) but also Entity Beans. In this last case, at the time of the passage in native request, the criterion will apply to the primary key. Of course, others could be added, as we will see it, but those are quasi systematically used to recover data. The operator "." is used to sail between the properties and the relations of Entity Beans. For example, in order to recover the user having a wallet of actions, one can represent navigation in the following way:
SELECT portfolio FROM Portfolio AS portfolio WHERE portfolio.user.id = 5
Correspondence in SQL :
select portfolio0_.id as id38 _, portfolio0_.name as name38 _, portfolio0.user_fk as user3_38 _ from Portfolio portfolio0 _ where portfolio0_.user_fk = ?
It is guessed rather clearly that the use of "." is similar, in this example, to call the method Portfolio.getUser()
Warning
Character of termination " ; "of requests SQL does not have to be used, under sorrow which PersistanceException is launched. Requests SELECT The most used request is undoubtedly SELECT, the request of research. The instruction to be used is SELECT like illustrates it the following example, where all the users are selected:
Page 38 of 100
17/10/09 18:17
SELECT usr FROM User AS usr select user0_.id as id21_, user0_.address_fk as address8_21_, user0_.password as password21_, user0_.lastName as lastName21_, user0_.firstName as firstName21_, user0_.login as login21_, user0_.sex as sex21_, user0_.birthDate as birthDate21_ from XUser user0_
There are many similarities with language SQL. However, it should well be understood that the difference comes owing to the fact that EJBQL is directed object. In the preceding example, ?To use? corresponds to the abstract diagram of Entity Bean User and ?usr? corresponds to one alias (as in SQL). The preceding example works directly with the User object, however it is sometimes practical to recover only the id, or the name, or the first name... With EJB 3, it is possible to specify the properties which one wishes to recover. It is enough to specify them in clause SELECT.
SELECT user.id, user.lastName FROM User AS user select user0_.id as col_0_0_, user0_.firstName as col_1_0_ from XUser user0_
Requests DELETE and UPDATE These requests will provide a whole of operations to modify or remove Entity Bean. Their common characteristic is to have only one entity in clause FROM. Thus, if you wish to remove or modify recordings of several different Entity Bean, you must carry out several requests. Here two examples showing the use of these requests.
DELETE FROM User AS user WHERE user.id = 5 delete from XUser where id=? UPDATE User AS user SET user.firstName = "Durand" WHERE user.id = 1 update XUser set firstName=? where id=?
Clause DELETE of EJBQL does not support the suppression in cascade. Indeed, even if the relation is configured with CascadeType.REMOVE or CascadeType.ALL, it will be necessary all the same to manually write their withdrawal of the data base. In this request DELETE, we are likely to receive exceptions if Entity Bean User would have relations. We have three possibilities then: To use the manager of persistence which applies the suppression in cascade. To explicitly write all requests EJBQL of suppressions in the good order. To use the possibilities of the data base and to manage the suppression cascade about it on the level of this one. In this last case, it?s possible to use the expression ON DELETE CASCADE for, for example, the data bases of the type MySQL version 5 and the engine of InnoDB storage. You will have, before, to check that the constraints of modifications in cascade were indeed applied. Here an extract of code SQL to be used:
Contraintes pour la table ÀccountInfo` ALTER TABLE ÀccountInfo` ADD CONSTRAINT `fk1` FOREIGN KEY (ìd`) REFERENCES `xuser` (ìd`) ON DELETE CASCADE; Contraintes pour la table `FINANCIALPRODUCT` ALTER TABLE `FINANCIALPRODUCT` ADD CONSTRAINT `fk2` FOREIGN KEY (`portfolio_fk`) REFERENCES `portfolio` (ìd`) ON DELETE CASCADE; Contraintes pour la table `Portfolio` ALTER TABLE `Portfolio` ADD CONSTRAINT `fk3` FOREIGN KEY (ùser_fk`) REFERENCES `xuser` (ìd`) ON DELETE CASCADE;
In this way, at the time of the removal of a user, all his wallets, financial products, and information will be automatically removed. Clause WHERE The permissions included in clause WHERE exist for the majority in a similar form with that which one can use in SQL. Here a list summarizing those most usually used: BETWEEN: conditional operator allowing to restrict the results according to an interval. The following example selects all the users having an identifier of 1500 to 2000.
SELECT user FROM User AS user WHERE user.id BETWEEN 1500 AND 2000 select user0_.id as id4_, user0_.address_fk as address8_4_, user0_.password as password4_, user0_.lastName as lastName4_, user0_.firstName as firstName4_, user0_.login as login4_, user0_.sex as sex4_, user0_.birthDate as birthDate4_ from XUser user0_ where user0_.id between ? and ?
LIKE: allows to compare the value of a field with a specified reason. The following request recovers, for example, all the accounts having a first name starting with "Jean".
SELECT user FROM User AS user WHERE user.firstName LIKE 'jean%' select user0_.id as id4_, user0_.address_fk as address8_4_, user0_.password as password4_, user0_.lastName as lastName4_, user0_.firstName as firstName4_, user0_.login as login4_, user0_.sex as sex4_, user0_.birthDate as birthDate4_ from XUser user0_ where user0_.firstName like ?
The reason is built with two special characters. First is "%" and it is used for a number of indefinite natures. The second, "_", represent only one character. If your character string would use really these two characters, you
Page 39 of 100

have at your disposal the escape character "\". Here some examples of use:
firstname LIKE `_axime' will return the entries such as Maxime, Aaxime... firstname LIKE ` Ma% ' will return the entries with Marc, Martine, Maxime... misc LIKE `%\_%' will return the entries containing the character ` _ ', such as ` java_bean', ` java _ ',
17/10/09 18:17
`_java' or ` _ '
IN: test a membership of a list of character strings. The following request recovers, for example, all the contacts located in France, Spain, and Belgium
SELECT user FROM User AS user WHERE user.address.country IN ('France', 'Spain', 'Belgium')
select user0_.id as id4_, user0_.address_fk as address8_4_, user0_.password as password4_, user0_.lastName as lastName4_, user0_.firstName as firstName4_, user0_.login as login4_, user0_.sex as sex4_, user0_.birthDate as birthDate4_ from XUser user0_, Address address1_ where user0_.address_fk=address1_.id and (address1_.country in ('France' , 'Espagne' , 'Belgique'))
IS NULL: test if a value is null. It acts of the default value defined when a field was not indicated. The following request returns, for example, the recordings where the login was not specified.
SELECT user FROM User AS user WHERE user.login IS NULL select user0_.id as id21_, user0_.address_fk as address8_21_, user0_.password as password21_, user0_.lastName as lastName21_, user0_.firstName as firstName21_, user0_.login as login21_, user0_.sex as sex21_, user0_.birthDate as birthDate21_ from XUser user0_ where user0_.login is null
MEMBER OF: test the membership of an authority to a collection, just like the method contains() of the interface java.util.Collection. The following example recovers the users having the wallet passed in parameter (we will further see the passage of the parameters in this chapter).
SELECT user FROM User AS user WHERE ?1 MEMBER OF user.portfolios select user0_.id as id21_, user0_.address_fk as address8_21_, user0_.password as password21_, user0_.lastName as lastName21_, user0_.firstName as firstName21_, user0_.login as login21_, user0_.sex as sex21_, user0_.birthDate as birthDate21_ from XUser user0_ where ? in (select portfolios1_.id from Portfolio portfolios1_ where user0_.id=portfolios1_.user_fk)
EMPTY: test if a collection is empty. For example, we here will turn over the list of the users not having any wallet of action.
SELECT user FROM User AS user WHERE user.portfolios IS EMPTY select user0_.id as id21_, user0_.address_fk as address8_21_, user0_.password as password21_, user0_.lastName as lastName21_, user0_.firstName as firstName21_, user0_.login as login21_, user0_.sex as sex21_, user0_.birthDate as birthDate21_ from XUser user0_ where not (exists (select portfolios1_.id from Portfolio portfolios1_ where user0_.id=portfolios1_.user_fk))
NOT: opposite the result of the condition. We can use it with preceding operators (NOT BETWEEN, NOT LIKE, NOT IN, IS NOT NULL...). Clause ORDER BY Clause ORDER BY makes it possible to arrange by order the results of a request, starting from one or more fields by using the alphanumeric order then alphabetical. To know exactly the implementation of this function, it is necessary to refer to the handbook of the data base. The following example turns over the list of the users ordered according to their identifier.
SELECT user FROM User AS user ORDER BY user.id ASC select user0_.id as id4_, user0_.address_fk as address8_4_, user0_.password as password4_, user0_.lastName as lastName4_, user0_.firstName as firstName4_, user0_.login as login4_, user0_.sex as sex4_, user0_.birthDate as birthDate4_ from XUser user0_ order by user0_.id
Here what one could recover (according to the data of the database): Table 1. Results of an ORDER BY ID First name 4 6 7 8 Cyril Frederic Olivier Maxime
10 Jean-Baptiste
Key word optional ASC means that the classification is made in an ascending way. To carry out it in a downward way, DESC should be used (larger with smallest). By defect, it is ASC which is applied.
Page 40 of 100

It is of course possible to combine these criteria. Thus, the following request posts the name by ascending order, however when two users have the same name, the sorting is done then on the first name, in an increasing way, then decreasing in the second example.
SELECT user FROM User AS user ORDER BY user.lastName, user.firstName ASC select user0_.id as col_0_0_, user0_.firstName as col_1_0_ from XUser user0_ order by user0_.lastName, user0_.firstName ASC SELECT user FROM User AS user ORDER BY user.lastName ASC, user.firstName DESC select user0_.id as col_0_0_, user0_.firstName as col_1_0_ from XUser user0_ order by user0_.lastName ASC, user0_.firstName DESC
17/10/09 18:17
Functions of aggregation The functions of aggregation are used to carry out operations on sets. One finds them in EJBQL via the following instructions: avg(): turn over an average by group count(): turn over the number of recordings sum(): turn over the sum of the values max(): turn over the highest value min(): turn over the lowest value sum(): turn over the sum of the values For example, you can use the function count() to know the number of users registered in your data base.
SELECT COUNT(user) FROM User AS user select count(user0_.id) as col_0_0_ from XUser user0_
It is also possible to use clause GROUP BY to apply the function of aggregation to a batch of recordings. Here an example allowing to turn over the number of wallets per user:
SELECT user.firstName, COUNT(user.portfolios) AS nbrPortfolio FROM User AS user GROUP BY user select user0_.id as col_0_0_, count(portfolios1_.id) as col_1_0_, user0_.id as id72_, user0_.address_fk as address8_72_, user0_.password as password72_, user0_.lastName as lastName72_, user0_.firstName as firstName72_, user0_.login as login72_, user0_.sex as sex72_, user0_.birthDate as birthDate72_ from XUser user0_ left outer join Portfolio portfolios1_ on user0_.id=portfolios1_.user_fk group by user0_.id
The results could be as follows, by supposing fictitious data: Table 2. First name Portfolios Cyril Frederic Maxime Olivier 2 4 1 9
Jean-Baptiste 5
The interest of GROUP BY in this request is to be able to apply function COUNT() to each user. Clause HAVING makes it possible to specify criteria, as with clause WHERE, on a column generated by one of the functions of aggregation. In the following example, we turn over only information when the number of financial wallets is higher than 2.
SELECT user.firstName, COUNT(user.portfolios) AS nbrPortfolio FROM User AS user GROUP BY user.firstName HAVING nbrPortfolio > 2
Note
In accordance with standards SQL, it is necessary to use clause HAVING in order to apply criteria to the result of a function. To handle the collections with the operator IN The major part of the relations uses collections. The course of their entries is particularly interesting because there does not exist in the relational logic of the SQL. We have for that the operator IN. He must be placed in clause FROM, and makes it possible to declare alias for the entries of a collection. For example, we can recover the whole of the wallets created, as follows:
SELECT portfolio FROM User AS user, IN (user.portfolios) portfolio select portfolio0_.id as id139_, portfolio0_.name as name139_, portfolio0_.user_fk as user3_139_ from Portfolio portfolio0_ where portfolio0_.user_fk=?
Page 41 of 100

We gather the elements contained in the collection user.porfolios, in alias " the portfolio ". So the request gathers the wallets of all the users and the load. The identifiers in clause FROM are declared of left on the right. When an identifier is declared, one can use it in the following declarations. The following request recovers all the financial products had by the user having identifier 42.
SELECT fp FROM User AS user, IN (user.portfolios) portfolio, IN (portfolio.financialProducts) fp WHERE user.id = 42 AND fp.quantity > 10 select financialp2_.id as id104_, financialp2_.quantity as quantity104_, financialp2_.buyValue as buyValue104_, financialp2_.productName as productN5_104_, financialp2_.buyDate as buyDate104_, financialp2_.portfolio_fk as portfolio10_104_, financialp2_.monthDuration as monthDur7_104_, financialp2_.rate as rate104_, financialp2_.price as price104_, financialp2_.financialproduct_type as financia1_104_ from XUser user0_ inner join Portfolio portfolios1_ on user0_.id=portfolios1_.user_fk inner join FINANCIALPRODUCT financialp2_ on portfolios1_.id=financialp2_.portfolio_fk where user0_.id=?
17/10/09 18:17
This operator allows to directly select the elements of a relation and to work with. In the preceding example, the request turns over FinancialProduct having a quantity higher than 10 of the user of id 42 (any confused wallet). One second function, ELEMENTS, fulfills the same role, but is in clause SELECT. Here a request with a similar result with the first example.
SELECT ELEMENTS(user.portfolios) FROM User AS user select portfolio0_.id as id139_3_, portfolio0_.name as name139_3_, portfolio0_.user_fk as user3_139_3_, user1_.id as id140_0_, user1_.address_fk as address8_140_0_, user1_.password as password140_0_, user1_.lastName as lastName140_0_, user1_.firstName as firstName140_0_, user1_.login as login140_0_, user1_.sex as sex140_0_, user1_.birthDate as birthDate140_0_, address2_.id as id143_1_, address2_.country as country143_1_, address2_.city as city143_1_, address2_.numero as numero143_1_, address2_.street as street143_1_, address2_.zipCode as zipCode143_1_, accountinf3_.id as id142_2_, accountinf3_.accountId as accountId142_2_, accountinf3_.cardNumber as cardNumber142_2_, accountinf3_.amount as amount142_2_ from Portfolio portfolio0_ left outer join XUser user1_ on portfolio0_.user_fk=user1_.id left outer join Address address2_ on user1_.address_fk=address2_.id left outer join AccountInfo accountinf3_ on user1_.id=accountinf3_.id where portfolio0_.id=?
Joints The joints make it possible to handle the relations between the entities. We will see that the functionalities available are multiple and will be able to adapt to many needs. To illustrate this declaration, we present the recovery of the wallets of actions, had by a user, various manners. By using the style ?thta?, with the relation between primary and key keys foreign:
SELECT user.firstName, ai.cardNumber FROM User AS user, AccountInfo AS ai WHERE u.accountInfo.id = ai.id select user0_.firstName as col_0_0_, accountinf1_.cardNumber as col_2_0_ from XUser user0_, AccountInfo accountinf1_ where user0_.id=accountinf1_.id
By using the relational properties:

SELECT user.firstName, user.accountInfo.cardNumber FROM User AS user select user0_.firstName as col_0_0_, accountinf1_.cardNumber as col_2_0_ from XUser user0_, AccountInfo accountinf1_ where user0_.id=accountinf1_.id
By using a joint via instruction JOIN:

SELECT user.firstName, ai.cardNumber FROM User AS user JOIN user.accountInfo AS ai select user0_.firstName as col_0_0_, accountinf1_.cardNumber as col_2_0_ from XUser user0_ inner join AccountInfo accountinf1_ on user0_.id=accountinf1_.id
Table 3. Results of a JOIN First name Cyril Ophlie Card number 1111-2222-3333-4444 2222-3333-4444-5555
The turned over results are the same ones for each request with some exceptions. Indeed, the operation of the joints is subtle. When a User entity does not have a relationship to the AccountInfo entity, the recording will not be turned over !
LEFT JOIN
In order to return the recordings of the Account entity, even if they do not have a relation, it is necessary to carry out a joint known as "open". For that, one uses the instructions LEFT OUTER JOIN or RIGHT OUTER JOIN, also existing in SQL. In EJBQL, the expression LEFT JOIN allows systematically to include the first entity in the result of the request. RIGHT JOIN, as for it, adds the results of the second entity.
Page 42 of 100
17/10/09 18:17
Note
Instruction OUTER, used in SQL, became optional. The following example uses an open joint. The results are then different.
SELECT user.firstName, user.lastName, ai.cardNumber FROM User AS user LEFT JOIN user.accountInfo AS ai
Table 4. Results of a LEFT JOIN First name Cyril Maxime Card number 1111-2222-3333-4444 2222-3333-4444-5555
Jean-Baptiste NULL
Indeed, the request from now on took into account the third recording, which does not have a relation with AccountInfo. This request carries out a "joint open on the left". Here its correspondence in SQL:
select user0_.firstName as col_0_0_, user0_.lastName as col_1_0_, accountinf1_.cardNumber as col_2_0_ from User user0_ left outer join AccountInfo accountinf1_ on user0_.accountinfo_fk=accountinf1_.id
INNER JOIN
We previously saw the use of the operator IN. The joint of the type ?INNER? causes the same result. It is however more familiar with the developers usually using the SQL. It is enough to use key word INNER JOIN to carry out this type of joint.
SELECT p FROM User u INNER JOIN u.portfolios p select user0_.firstName as col_0_0_, user0_.lastName as col_1_0_, accountinf1_.cardNumber as col_2_0_ from XUser user0_ inner join AccountInfo accountinf1_ on user0_.id=accountinf1_.id
The preceding request turns over the whole of the wallets created whatever the user. It is however simpler to use the operator IN. Here correspondence using ?IN?:
SELECT p FROM User u, IN(u.portfolios) p
FETCH JOIN
We saw previously that it was possible to use a mechanism of the lazy loading. In this case, when the application reaches a property marked with lazy, the supplier of persistence must charge it.
Query query = entityManager.createQuery("SELECT u FROM User u WHERE u.id = :userId"); User user = (User) query.setParameter("userId", 1).getSingleResult(); Iterator<Portfolio> portfoliosIt = user.getPortfolios().iterator(); while(portfoliosIt.hasNext()) { Portfolio p = portfoliosIt.next(); p.getFinancialProducts().size(); }
This example charges the user of id 1 and initializes its wallets and the associated financial products. That poses problems of performances however. Indeed, the engine of persistence must carry out a request with line 2 then for each loading of the associated financial products (line 5). This one operates N+1 requests then (N being the number of wallet). To optimize that, it is necessary to use a request EJBQL with a joint of the type ?FETCH?.
SELECT U FROM To use U INNER JOIN FETCH u.portfolio p LEFT JOIN FETCH p.financalProducts select user0_.id have id310_0 _, portfolios1_.id have id309_1 _, user0_.address_fk have address8_310_0 _, user0_.password have password310_0 _, user0_.lastName have lastName310_0 _, user0_.firstName have firstName310_0 _, user0_.login have login310_0 _, user0_.sex have sex310_0 _, user0_.birthDate have birthDate310_0 _, portfolios1_.name have name309_1 _, portfolios1_.user_fk have user3_309_1 _, portfolios1_.user_fk have user3_0 __, portfolios1_.id have id0 __ from XUser user0 _ left outer join Portfolio portfolios1 _ one user0_.id=portfolios1_.user_fk left outer join FINANCIALPRODUCT financialp2 _ one portfolios1_.id=financialp2_.portfolio_fk
A joint ?fetch? does not need normally to define alias except when you wish to use the concept of the ?fetch recursively?. Thanks to this modification, only one request is carried out. The use of this type of joint in a program is a need for the optimization and the improvement of the performances. Indeed, it is strongly advised to avoid too much outward journey and return with the data base. Management of Polymorphism EJBQL supports polymorphism, i.e. the requests relating to a hierarchy of objects.
Page 43 of 100
17/10/09 18:17
The execution of the following request turns over all the recordings dependent on the FinancialProduct entity and thus of its subclasses.
SELECT fi FROM FinancialProduct AS fi
The collection of result contains objects of the Bond type or Stock, i.e. the concrete types of the hierarchy. Under requests The underrequests can beings placed in clauses WHERE and HAVING. Like their equivalent SQL, they make it possible to imbricate the requests. The following example selects the users having more than 3 financial wallets.
SELECT user FROM User user WHERE ( SELECT COUNT(portfolio) FROM Portfolio AS portfolio WHERE portfolio.user=user GROUP BY user ) >3 select user0_.id as id327_, user0_.address_fk as address8_327_, user0_.password as password327_, user0_.lastName as lastName327_, user0_.firstName as firstName327_, user0_.login as login327_, user0_.sex as sex327_, user0_.birthDate as birthDate327_ from XUser user0_ where (select count(portfolio1_.id) from Portfolio portfolio1_ where portfolio1_.user_fk=user0_.id group by user0_.id)>?
It is noticed that one alias reuses to use of the principal request in the underrequest. One of the principal interests of the underrequests is to be able to replace the joints, in particular in the requests of the type UPDATE and DELETE. The following request removes all the financial products where the user has a id having for value 5:
DELETE FROM FinancialProduct AS fp WHERE fp.portfolio IN ( SELECT portfolio FROM Portfolio AS portfolio WHERE portfolio.user IN ( SELECT user FROM User AS user WHERE user.login = 5 ) ) delete from FINANCIALPRODUCT where portfolio_fk in (select id from Portfolio portfolio1_ where portfolio1_.user_fk in (select id from XUser user2_ where user2_.id = 5))
Note
Use the underrequests when you cannot make differently. We advise you to study, initially, the use of joints or instructions such as IN, ELEMENTS... which are obligatory besides in systems not taking into account the underrequests. When under request is likely to turn over several lines, it is then possible to quantify the result having to be turned over. For that, one uses the expressions: ALL turns over true if all the results of the request checks the condition. SOME turns over true so at least a result checks the condition ANY turns over true if no result checks the condition
API Query
API Query is the essential point for the junction between the application and the execution of requests EJBQL. The methods of this one are gathered in the interface javax.persistence.Query. We will progressively detail the various methods of this one. The principal interest of this API is to be able to create dynamic requests in the form of simple character strings, and either a static way in the descriptor of deployment. There are various means of recovering an object of the Query type. The corresponding methods are gathered in the EntityManager interface. Here a simple example:
Query query = entityManager.createQuery("SELECT user FROM User As user"); List<User> listUsers = query.getResultList();
We recover a Query object here via the method createQuery() of EntityManager. It is then enough to call the method getResultList() to carry out the request and to recover the result of this one.
Page 44 of 100

Here a description of the various traditional methods of the Query interface.
java.util.List getResultList();
17/10/09 18:17
This method carries out the request and turns over the whole of the results of this one. It makes it possible for example to recover a whole of Entity Beans complete. It is then possible to specify several properties in clause SELECT in order to recover only certain values of the entity, in the form of table.
Query query = entityManager.createQuery("SELECT user.id, user.lastName FROM User As user"); List<Object[]> listUsers = query.getResultList(); for(Object[] valueArray : listUsers){ Integer id = (Integer) valueArray[0]; String name = (String) valueArray[1]; }
In this case, the method getResultList() turns over a list of table of object (" Object[ ] ").
java.lang.Object getSingleResult();
This method carries out the request and turns over a single result. If the number of results is higher than 1, a NonUniqueResultException exception is raised. Conversely, if no result is found, an exception of the EntityNotFoundException type is raised. This method must be used only if you are sure that the request turns over only one single result.
Query query = entityManager.createQuery("SELECT user FROM User AS user WHERE user.login = 'durand.dupont'"); User currentUser = (User) query.getSingleResult();
In this example, the property login is single. So we are sure that the method cannot return several results.
setMaxResults(int max) and setFirstResult(int first)
These two methods respectively define the maximum number of results and the index of the first element to be turned over. Those make it possible to limit the results of the request. Indeed, if the request tries to turn over several thousands of lines, you are likely to quickly reduce the performances of your application. Moreover, one generally does not work with the whole of the results of only one blow but left by part.
Query query = entityManager.createQuery("SELECT user FROM User As user"); query.setMaxResults(30); query.setFirstResults(10); List<User> listUsers = query.getResultList();
Conclusion
In this essential about EJB3, we've first seen that they locate in the center of your application, providing lots of assets (like the object persistence's one and a functionnal and performant client/server model). Furthermore, during the setting up of this technology, the code writing is kind of simple and is very well inscribed in the Java object Model... the complicated thing being to understand and to analyse the application architecture. The trade layers are also more efficient and simpler to write.
Practices
Questions
1.1. What does EJB means : Enterprise Java BeansEnterprise Java BasesEntity Java BeansEntity Java Bases 1.2. Which of these beans are valid Session beans: Remote session beanLocal session beanCommon session beanUnique session bean 1.3. What are the different JMS distribution models? Peer to peerPoint to pointPublish and subscribeSend to all 1.4. What is the difference between Stateful and Stateless session beans? It's the same thingThey're not relatedA stateless session bean keep information between two calls while stateful forget thoses informationsA stateful session bean keep information between two calls while stateless forget thoses informations 1.5. The @Id annotation is used to specify a primary key. How does it works? It specify the column choosen to sort multirow requestsAn attribute used as an identifier of the objectIt's like a foreign key but in local onlyIt's a table identifier common to all instances of the class 1.6. Wich of thoses servers can handle EJB? GlassFishJBossTomcatOracle Application Server 1.7. How do you get an entity away from the database: Using the remove() method Using the delete() method Using the clear() method Using the erase() method 1.8. Choose the best example representing a "One to one" relationship: A dog has an owner, an owner has many dogsA teacher has many students, a student has many teachersA mailbox belongs to an house, a house has a mailbox 1.9. Choose the best example representing a "One to many" relationship: A dog has an owner, an owner has many dogsA teacher has many students, a student has many teachersA mailbox belongs to an house, a house has a mailbox 1.10. Choose the best example representing a "Many to many" relationship: A dog has an owner, an owner has many dogsA teacher has many students, a student has many teachersA mailbox belongs to an house, a house has a mailbox 1.1. What does EJB means : Enterprise Java Beans Enterprise Java Bases Entity Java Beans Entity Java Bases
Page 45 of 100

1.2. Which of these beans are valid Session beans: Remote session bean Local session bean Common session bean Unique session bean 1.3. What are the different JMS distribution models? Peer to peer Point to point Publish and subscribe Send to all 1.4. What is the difference between Stateful and Stateless session beans? It's the same thing They're not related A stateless session bean keep information between two calls while stateful forget thoses informations A stateful session bean keep information between two calls while stateless forget thoses informations 1.5. The @Id annotation is used to specify a primary key. How does it works? It specify the column choosen to sort multirow requests An attribute used as an identifier of the object It's like a foreign key but in local only It's a table identifier common to all instances of the class 1.6. Wich of thoses servers can handle EJB? GlassFish JBoss Tomcat Oracle Application Server 1.7. How do you get an entity away from the database: Using the remove() method Using the delete() method Using the clear() method Using the erase() method 1.8. Choose the best example representing a "One to one" relationship: A dog has an owner, an owner has many dogs A teacher has many students, a student has many teachers A mailbox belongs to an house, a house has a mailbox 1.9. Choose the best example representing a "One to many" relationship: A dog has an owner, an owner has many dogs A teacher has many students, a student has many teachers A mailbox belongs to an house, a house has a mailbox 1.10. Choose the best example representing a "Many to many" relationship: A dog has an owner, an owner has many dogs A teacher has many students, a student has many teachers A mailbox belongs to an house, a house has a mailbox
17/10/09 18:17
Answers
1.1. What does EJB means : Enterprise Java BeansEnterprise Java BasesEntity Java BeansEntity Java Bases 1.2. Which of these beans are valid Session beans: Remote session beanLocal session beanCommon session beanUnique session bean 1.3. What are the different JMS distribution models? Peer to peerPoint to pointPublish and subscribeSend to all
Page 46 of 100

1.4. What is the difference between Stateful and Stateless session beans? It's the same thingThey're not relatedA stateless session bean keep information between two calls while stateful forget thoses informationsA stateful session bean keep information between two calls while stateless forget thoses informations 1.5. The @Id annotation is used to specify a primary key. How does it works? The annotation specify the column choosen to sort multirow requestsAn attribute is used as identifier of the objectIt's like a foreign key but in local onlyIt's a table identifier common to all instances of the class 1.6. Wich of thoses servers can handle EJB? GlassFishJBossTomcatOracle Application Server 1.7. How do you get an entity away from the database: Using the remove() method Using the delete() method Using the clear() method Using the erase() method 1.8. Choose the best example representing a "One to one" relationship: A dog has an owner, an owner has many dogsA teacher has many students, a student has many teachersA mailbox belongs to an house, a house has a mailbox 1.9. Choose the best example representing a "One to many - Many to one" relationship: A dog has an owner, an owner has many dogsA teacher has many students, a student has many teachersA mailbox belongs to an house, a house has a mailbox 1.10. Choose the best example representing a "Many to many" relationship: A dog has an owner, an owner has many dogsA teacher has many students, a student has many teachersA mailbox belongs to an house, a house has a mailbox 1.1. What does EJB means : Enterprise Java Beans Enterprise Java Bases Entity Java Beans Entity Java Bases
17/10/09 18:17
1.2.
Which of these beans are valid Session beans: Remote session bean Local session bean Common session bean Unique session bean
1.3.
What are the different JMS distribution models? Peer to peer Point to point Publish and subscribe Send to all
1.4.
What is the difference between Stateful and Stateless session beans? It's the same thing They're not related A stateless session bean keep information between two calls while stateful forget thoses informations A stateful session bean keep information between two calls while stateless forget thoses informations
1.5.
The @Id annotation is used to specify a primary key. How does it works? The annotation specify the column choosen to sort multirow requests An attribute is used as identifier of the object It's like a foreign key but in local only It's a table identifier common to all instances of the class
Page 47 of 100

1.6. Wich of thoses servers can handle EJB? GlassFish JBoss Tomcat Oracle Application Server
17/10/09 18:17
1.7.
How do you get an entity away from the database: Using the remove() method Using the delete() method Using the clear() method Using the erase() method
1.8.
Choose the best example representing a "One to one" relationship: A dog has an owner, an owner has many dogs A teacher has many students, a student has many teachers A mailbox belongs to an house, a house has a mailbox
1.9.
Choose the best example representing a "One to many - Many to one" relationship: A dog has an owner, an owner has many dogs
A teacher has many students, a student has many teachers A mailbox belongs to an house, a house has a mailbox
1.10. Choose the best example representing a "Many to many" relationship: A dog has an owner, an owner has many dogs A teacher has many students, a student has many teachers A mailbox belongs to an house, a house has a mailbox
Chapitre 2 JSF Web framework

Objectives of this chapter :
Know when to use JSF Understand its architecture Display web pages Validate forms Realize that a web application can be very close from a Swing application.
Page 48 of 100
17/10/09 18:17
Introduction
Servlet / JSP limitations
The first step to create a Web Site in Java is to use Servlet and JSP. Even if it?s possible to create a Site with only these technologies it?s clear that Servlet better suit for treatment and JSP for visual. But Servlet/JSP has some limitations: Create its own tags is difficult There are no highlevel tags It?s hard to process user inputs It?s hard for a beginner to create a Site with a clean architecture. There are no guides to help you.
Java Server Faces presentation

Java Server Faces (JSF) is a Web Framework. It provides highlevel components to quickly create complex Web Site. It also helps to manage all commons tasks like data validation, navigation management. JSF is based on the model MVC (ModelViewControler) and provides a notion of Web components similar to Swing. Web components can holds listeners (clic on a button, clic on a link, ?) on server side. JSF uses a HTML/Object mapping, it means that a HTML component will be mapped to a JSF component. This mapping is done on the server side. This mapping allows us to create a site in Java or to use HTML/JSFP/JSF tags. Of course you can mix the two techniques. When a user visits a page, JSF components will be transformed into HTML and viceversa. This transformation is done thanks to the HTML/Object mapping. Finally JSF manage all navigations rules into a unique file named "navigation file". This helps to see how navigation works for a Site at a glance.. JSF offers the following services: Provides a HTML/Object mapping Save the state of JSF components between requests Transform JSF components into HTML Manage events (click on a button, field modification, ?) on server side Instanciate and attach JavaBeans to the session, request or application automatically Extensibility, numerous JSF components are available on the Internet. This goes from calendar to tree by going through sortable table and progress bar Support a plugin system which can be used to modify the way JSF works Manage data conversion (can convert a String into a Date, a String into a business object and viceversa...) Validate users requests (test field length, content type, ?) Manage errors and exceptions and provides clear error messages Manage navigation depending on interaction on a data model Manage internationalization JSF Audience A large audience can use JSF. From application developer, to designer, everyone can use JSF. There are three main categories of people between five. Application architect which will create application, define navigation file, classes/libs to use to make the link between view and services layers Developers who implements all the Web Site Page designers who will works with HTML/JSP/JSF tags Last two categories of people which use JSF are: People who want to extends JSF, to create custom components IDE creators who will use JSF as the base of the IDE and extends JSF functionalities thanks to custom components. For example Sun has created Java Studio Creator, an IDE dedicated to JSF and which JSF as its core.
JSF Evolution
JSF is a specification proposed by the JCP (Java Community Process : www.jcp.org ). So there is not only one implementation of JSF, but only a document which describes how JSF works. Offical JSF specifications can be downloaded at : http://jcp.org/en/jsr/detail?id=127 for JSF 1.0 et http://jcp.org/en/jsr/detail?id=252 for JSF 1.2. Sun provides a reference implementation for each version. Apache provides its own one named "MyFaces" (currently only for JSF 1.1). JSF version 1.0 and 1.1 were not part of J2EE. It?s only since JEE 5 that JSF 1.2 has become a standard.
Page 49 of 100

JSF 1.2 is based on the following librairies: JSF version 2.1 Servlet 2.5 JSE 5.0 JEE 5.0 JavaBeans 1.0.1 JSTL 1.2 All JEE 5 application servers supports JSF 1.2. If you don?t have a JEE 5 server, you can still use JSF 1.1 with a Servlet/JSP 2.3/1.2 server or JSF 1.2 with a Servlet/JSP 2.5/2.1 server. In a global manner, to run JSF 1.2 with a non JEE 5 server, you have to include all JSF librairies into your wars. However there may be unexpected behaviors depending on your application server. Check the documentation of your server before deploying a JSF application. This lesson has been created for JSF 1.1 and 1.2. Elements specific to JSF 1.2 are specified.
17/10/09 18:17
Difference with Struts

Struts and JSF can look the same. There has been created to go beyond the limits of Servlet/JSP. They provide: Managed Beans, it means that their lifecycle are managed by the container Form validation Navigation defined in only one file JSF also support events and independence of HTML rendering. JSF pages can be used to generate XML, SVG, ... But they also have a different way of working. Struts use an actionresponse model. Each user request to Struts pages must go through a mini Servlet (action class) that can do some process and define the JSP target page. With JSF a request is directly targeted to a JSP/JSF page. Then the page can use JavaBeans to define what process to execute. This model promotes code reuse thanks to components. Finally JSF is a JEE 5 standard which ensure that community and majors actors (Oracle with ADF/MyFaces, Sun with Java Studio Creator 2, ?) will maintain it.
JSF architecture
JSF is like Swing but for Web. JSF use components to represent structure of a page. Components provide methods to manage listeners, validate user input and data conversion. All components exist as Java classes, so you can use them inside Java code. But in practice all components are manipulated through JSF tags. By default JSF use HTML/JSP/JSF tags but in the chapter "9 Facelets" we?ll see that we can use another tag libs. JSF components provides: JavaBeans interaction. JavaBeans represents the model and are used to interact with lower layers of your application Rendering system used to translate JSP/JSF tags to HTML Obersvator/Observer system Conversion model Validation model All these services are manipulated through JSF tags, which is easier than in Java code.
In practice components are mostly invisible, it?s like a JavaBean is directly linked to JSF tags. In MVC model, JSF components are the view, JavaBeans represents model. Controller is the Faces Servlet.
And JSF use a file which summarize: all navigation rules
Page 50 of 100

declaration of managed beans. With the navigation file you can see how user request are processed. You can even do conditional navigation. JavaBeans that are declared in the configuration file are named "managed bean". The container instantiate beans when a page need it.
17/10/09 18:17
JSF integration inside a JEE architecture

To reuse the architecture schema from the JEE lesson, JSF correspond to Application and Client layers. It?s possible to interact with EJBs or any other type of service layer. JavaBeans provide access to Service layer. Here?s an example of an application with EJB + JSF:
In a small application, it?s also possible to directly interact with a database from JavaBeans. Here?s an example of a site architecture:
LifeCycle We?ll now see how server process a JSF request. JSF is made of a single Servlet. This Servlet is used to transform JSF tags into components that are manipulated on the server side. And it also produces HTML from JSF tags. When a client send a HTTP request to a server. The Servlet first retrieve the component tree which maps to a requested JSF page by looking to identifiant put inside of the HTML code. JSF Servlet can be executed in a Servlet or Portlet container. Class which manages lifecycle is "javax.faces.context.FacesContext". When a request arrive on the server, a new instance of FacesContext is created and process the request. Let?s see in details how request processing works:
Restore View
When a request arrive on the server. It transmit it to the JSF Servlet. Then JSF Servlet create component tree which maps to the JSF page. Once all JSF components are instantiated, this phase is over.
Page 51 of 100

Apply Request Values
17/10/09 18:17
If parameters has been passed with the request, Servlet set all news values to corresponding component. For example if an user send an form, values of textfields are set to components which reprensent these text fields. Some components can trigger an event once its value change. These events are processed during the "Invoke Application" phase or immediately if the "immediate" attribute is set to true. Event processing will be review in details in the chapter: " Behaviors ".
Process Validations
Components that accept user entry can define validation rules. Servlet process these rules during this phase. The property "immediate" can be used to force processing of validation rules during the phase "Apply Request Values".
Update Model Values
From now, all update values has been done on components. The model (JavaBeans) which are mapped to components will now be updated to reflect these new values.
Invoke Application
During this phase, all events are processed. This include events triggered during "Apply Request Values" phase. Finally the navigation is resolved, this means that destination page is determined.
Render Response
In this last phase, JSF page is translated to HTML.
Develop with JSF

What are the steps to develop a JSF application? We?ll now see with a "Hello World" what are the minimal steps to create a JSF site. Install JSF Activate JSF in "web.xml" file Create JSF pages Create JavaBeans (optional) Configure application with "faces-config.xml" file (optional)
JSF installation
If you want to use JSF 1.2, the simplest thing is to use a JEE 5 server. In this case, JSF support is integrated. You can download GlassFish at: https://glassfish.dev.java.net/ . To use JSF 1.1 or JSF 1.2 on a server that don?t support JSF, you have to download an implementation. You can download Sun implementation at: http://java.sun.com/javaee/javaserverfaces/download.html In the "lib" folder of the zip file, there are all jars necessaries to develop a JSF application. These jars must be placed under "WEB-INF/ lib" of Web archive (War). Jars necessaries to JSF 1.1 are: " jsfapi. jar ", contains JSF classes definition (package javax.faces) " jsfimpl. jar ", contains implementation of JSF classes " jstl.jar ", allow usage of JSTL tags. These tags are referenced by JSF implementation " standard.jar ", allow usage of standard tags. These tags are referenced by JSF implementation " commonsbeanutils. jar ", utility classes to manipulate JavaBeans " commonsdigester .jar ", to manipulate XML " commonscollections. jar ", extension to Collections framework " commonslogging. jar ", to create logs For JSF 1.2, necessaries jars are: " jsfapi. jar ", contains JSF classes definition (package javax.faces) " jsfimpl. jar ", contains implementation of JSF classes
Enable JSF
First activate JSF in "web.xml". You have to create a redirect user requests to JSF Servlet. In this example, we?ll redirect all requests which begins with "/faces/" to JSF Servlet.
<?xml version='1.0' encoding='UTF8'?> <!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> <display-name>Application name</display-name>  <servlet> <servlet-name>Faces Servlet</servlet-name> <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
Page 52 of 100
17/10/09 18:17
</servlet>  <servlet-mapping> <servlet-name>Faces Servlet</servlet-name> <url-pattern>/faces/*</url-pattern> </servlet-mapping> </web-app>
For JSF 1.2, header of the file is:

<?xml version='1.0' encoding='UTF8'?> <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/webapp_2_5.xsd">
JSF pages must have ".jsp" extension. It?s a JSF parameter that you can modify, see chapter "6.3 Context parameters". An url like "/faces/index.jsp" is used to access JSF pages. If you try to access directly the jsp page (/index.jsp), the request will not go through JSF Servlet and all JSF tags will not be processed. Here?s another example of mapping. To acess a page you have to type it?s URL but replace its extension with ".jsf".
<web-app> <servlet> <servlet-name>Faces Servlet</servlet-name> <servlet-class>javax.faces.webapp.FacesServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>Faces Servlet</servlet-name> <url-pattern>*.jsf</url-pattern> </servlet-mapping> </web-app>
Although you access page by using a ".jsf" extension. All pages need to have the ".jsp" extension when you create it. When client ask for "index.jsf" page, JSF Servlet look for "index.jsp" on the server and process it like a JSF page.
Hello World
Now that JSF is activated we can write our first. Here?s a basic page:
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> <%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %> <html> <head> <title>First JSF page</title> </head> <body> <f:view> Hello World </f:view> </body> </html>
The first 2 lines declare JSF taglibs. The following is a classic HTML structure. The only difference is the
<f:view>...</f:view>
tag. It?s the root tag for all others JSF tags. In this example, we can see we can display text directly on the page. However it exists dedicated tags for output, especially for internationalization. War Structure Once the JSF pages are created, there must be packaged into a War (Web Archive). A War must have the following structure: Table 1. WEB-INF/classes WEB-INF/lib WEB-INF/web.xml *.jsp All jsp pages Contains java classes (like JavaBeans) All libraries (jars) of the project.
WEB-INF/faces-config.xml Configuratin file(optional)
For example in JSF 1.1, we have:
Page 53 of 100
17/10/09 18:17
Deployment
Even if your server supports JSF, you can package your own JSF jar because it?s always the jar of the server which have priority. If you want to add support of JSF on a server, you can copy all the JSF jars in the libraries folder of the server. For example in Tomcat, you can put them in the folder "TOMCAT_HOME/shared/ lib". This folder is specific to the server, so you have to check the server documentation to find the good folder. JBoss JBoss supports JSF 1.1 since its version 4.0.3. This support is based on the implementation of Apache : MyFaces. If you want to use the Sun implementation, you have to delete the MyFaces jars on JBoss. They are on the folder: JBOSS_HOME/server/default/deploy/jboss-web-tomcat55.sar/jsf-lib If "default" is the configuration that you use. Then, you have to package the Sun jars of JSF 1.1 into your War. Support of JSF 1.2 is planned for JBoss 5. Example We?ll now see a little web site made in JSF. The goal is to show how look JSF tags and code. The web site uses validation and errors displaying, site navigation mechanisms. There are only 2 pages. The first display a form used to register. When the user submit it, data of the form are displayed in a second page. If they?re validation errors (missing field, too short password, ?) messages are displayed directly on the form. Let?s start with the form page, "Register.jsp":
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> <%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %> <html> <head> <title>Register</title> </head> <body> <f:view> <h1>Register</h1> <h:form>  <h:inputText id="lastName" required="true" size="21" maxlength="20" value="#{user.lastName}">  <h:outputLabel for="lastName" value="Last name: "/>  <f:validateLength minimum="3" maximum="20"/> </h:inputText>  <h:message for="lastName" style="color: red"/> <br/>  <h:inputText id="firstName" required="true" size="21" maxlength="20" value="#{user.firstName}"> <h:outputLabel for="firstName" value="First name: "/> <f:validateLength minimum="3" maximum="20"/> </h:inputText> <h:message for="firstName" style="color: red"/> <br/>  <h:inputSecret id="password" required="true" size="21" maxlength="20" value="#{user.password}"> <h:outputLabel for="password" value="Password: "/> <f:validateLength minimum="3" maximum="20"/> </h:inputSecret> <h:message for="password" style="color: red"/> <br/> <h:commandButton value="Submit" action="success"/> </h:form> </f:view> </body> </html>
Syntax "#{user.lastName}" allows to use a JavaBean. Here "user" is the name of a bean and "lastName" is the name of one of its properties. Now we?ll look at the bean class:
package com.labosun; public class User { private String lastName; private String firstName;
Page 54 of 100
17/10/09 18:17
private String password; public String getLastName() { return lastName; } public String getPassword() { return password; } public String getFirstName() { return firstName; } public void setFirstName(String firstName) { this.firstName = firstName; } public void setLastName(String lastName) { this. lastName = lastName; } public void setPassword(String password) { this. password = password; } }
Now let?s see the configuration file of JSF (faces-config.xml). This file gives a name to the previous bean.
<managed-bean>  <managed-bean-name>user</managed-bean-name>  <managed-bean-class>com.labosun.User</managed-bean-class>  <managed-bean-scope>session</managed-bean-scope> </managed-bean>
Finally we?ll look at the Confirmation page. This page display the lastname and the firstname of the user. Confirmation.jsp :
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> <%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %> <html> <head> <title>Registration</title> </head> <body> <f:view> <h1>Successful registration </h1> Welcome <h:outputText value="#{user.firstName} #{user.lastName}" /> </f:view> </body> </html>
As you can see, syntax "#{user.prenom}" is used again here to reference the bean. The last step for this demo is to define a navigation rule, so when the user click and the submit button, he goes to the confirmation page. For recall, the code for the submit button is:
<h:commandButton value="Submit" action="success"/>
"Action" attribute define a string which will be linked to the confirmation page..
<navigation-rule>  <from-view-id>/Register.jsp</from-view-id> <navigation-case>  <from-outcome>success</from-outcome>  <to-view-id>/Confirmation.jsp</to-view-id> </navigation-case> </navigation-rule>
Now we?ll see the result:
Site design is not good, but we?ll see later how to do it better. When the user submit the form, the confirmation page is displayed:
If the form is not valid, the following messages are displayed:
Page 55 of 100

You can customize these messages as explained in the chapter "8.2.1 Customize messages".
17/10/09 18:17
Basic elements
Root class of all components in JSF is "javax.faces.component.UIComponent". This class definie attributes shared by all JSF components. This components are not specifics to HTML, but provide similar functionalities: links, table, form, buttons, combo box, list, ... HTML specific components subclass a standard component. They are in the package "javax.faces.component.html". In practice, you?ll use JSF tags to use components and the attributes of the tag to call the properties or methods of this component. For example, the UIComponent class define a property "id". This property is accessible directly from a JSF tag with an attribute of the same name.
public class UIComponent { private int id; public int getId() {...} public void setId() {...} }
And for any JSF tag, you can write:

<h:baliseJSF id="identifiant " />
Be careful: JSF tags can?t use some properties. There are some tags attributes that don?t map to component property or method.
Behaviors
There are 5 interfaces that can define a behavior to components. Table 1. Interface StateHolder NamingContainer ValueHolder EditableValueHolder ActionSource Description For component that maintain a state between user requests. UIComponent implements this interface. So all JSF implements it. Indicates that all children components must have a unique Id. It?s not mandatory to set an Id (server will automatically define one), but if you define one, it must be unique. The component has a value. This value can be linked to a JavaBean. The value can be converted in a specific type, see chapter "7.3 Data conversion". Extend ValueHolder. The value of the component can be edited and when it happens, a event is fired on the server side. And you can defini validation rules for editing. State that this component will fire an event when the user activates it. Example : a HTML link fire an event, when a user click on it.
Note: In JSF 1.2, interface " ActionSource " has been subclassed into " ActionSource2 ". JSF tags which implements ValueHolder has a "converter" attribute. It?s used to define how the value must be converted to another type. For example, you can convert the String "10/05/06" into a Date object directly. JSF components which implements EditableValueHolder has the following attributes: "validator", define the method of a bean that will validate the used entry. "valueChangeListener", define the method that will be called when the value of the component change. JSF components which implements ActionSource has the attribute "actionListener ". It define the method that will be called when the user activate this component. Behaviors are detailed in chapter "Behaviors".
Generics behaviors
JSF is independent from HTML. That?s why there is generic rendering system for tags and different implementations for every language. But in practice there is only the HTML implementatio. So they are 2 categories of components, the first for generic JSF and the second one for HTML. The following table sum up all generic components. They?re all from the package "javax.faces.component". Table 2. Class (implemented interfaces) UICommand (ActionSource) UIData (NamingContainer) UIForm (NamingContainer) UIGraphic UIInput (extends UIOutput) (EditableValueHolder) UIMessage et UIMessages UIOutput (ValueHolder) UIPanel UISelectBoolean (extends UIInput) Description Root class for all components that can fire an event. Used to manipulates data from a Collection , an array or a ResulSet. Represents a form. Used to display pictures. Used to enter data. Used to display messages. See chapter "8.2 Messages management". Used to display text. Group JSF components into a single one.
Page 56 of 100

UISelectBoolean (extends UIInput) (EditableValueHolder) UISelectMany (extends UIInput) (EditableValueHolder) Used to manipulate a Boolean value. Used to select multiples values from a list.
17/10/09 18:17
UISelectOne (extends UIInput) (EditableValueHolder) Used to select a single value from a list.
All these components have the following attributes. Attribute id This attribute defines an identifier for component. It?s not mandatory to use an id. It?s useful to reference components on a page. A indentifier must respect the following rules: It must begins with a letter (see method String.Character.isLetter()) or the character '_'. Others characters can be letters, digits (see method Character.isDigit()),'' or '_'. Example:
<h:JSFtag id="identifier" />
Note: To optimize JSF performance, it?s recommended to use short id. Renderer attribute It?s a boolean that define if the components is displayed or not Example:
<h:JSFtag renderer="false" />
This attribute can be used to display a message only if a search has returned no results. Immediate attribute As seen in chapter " LifeCycle", this attribute affect the lifecycle.
HTML components
HTML components are located in the package "javax.faces.component.html". See chapter "5 JSF Taglib" for a complete list This chapter only covers commons attributes of these components. You can use previous attributes and the following attributes: CSS style This attribute define the CSS code of the tag. Here?s an example with the tag <h:outputText /> that display a text.
<h:outputText style="font-size: 150%; color: red" value="Hello"/>
That?s translated in the following HTML :

<span style="font-size: 150%; color: red">Hello</span>
CSS class It defines the CSS class of a tag. Example:

<h:baliseJSF styleClass="title1" />
escape Only some components have this attribute. If set to true, characters '<', '>' and '&' are converted into HTML code. JavaScript events All tags that represents a HTML tags, also share the same javascript attributes. Here?s a list of javascript attributes: " onclick, ondblclick, onblur, onchange, onclick, ondblclick, onfocus, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onreset, onselect, et onsubmit ". Linking between JSF Components and JavaBeans JavaBeans represents the model part into the MVC model. This model clearly separate different layer of an application. They are to way to bind a component to a JavaBean: Only the value of the component is bind to a JavaBean property (only for component that has a value). The component itself is bind to a JavaBean property. The syntax to use JavaBean in JSF tags is EL (Expression Language). It web specific language. Since JSF 1.2 it?s been unified with JSP language under the name Unified Expression Language. This lesson only cover JSF aspects of this syntax. The next chapter "4.5 Unified Expression language" details all JSF features of this syntax. An EL expression start with "#{" and end with "}".This syntax use an object oriented notation. You can used any variable of a page just by using its name. From this variable you can use any property or method. Example:
#{javaBean.method}
Page 57 of 100
17/10/09 18:17
#{javaBean.property}
Value
To bind the value of a component to a bean property, you have to use the attribute "value" and specify the referenced bean with EL syntax. Example:
<h:JSFTag value="#{javaBean.property}" />
There are restrictions on the type that you can bind: Table 3. Component UIInput, UIOutput, UISelectItem, UISelectOne UIData UISelectBoolean UISelectItems UISelectMany Possible values A primitive, a String, a Number or any class that have a converter. See chapter "7.3 Data conversion" for more information. JavaBean array or list, Simple JavaBean, java.sql.ResultSet, javax.servlet.jsp.jstl.sql.Result or javax.sql.RowSet. boolean or Boolean String, Collection, Tableau or Map Array or List.
Restrictions will be detailed in following chapters.

Instance
If you want to bind a component instance to a bean property. The property must be of the same type that the JSF component. For example, if you want to bind the component HtmlOutputText to a JavaBean. You first declare the following property:
public class LinkedBean { private HtmlOutputText composant; public HtmlOutputText getComposant() { return this.composant; } public void setComposant(HtmlOutputText c) { this.composant = c; } }
And then, you just specify the bean property with the attribute "binding":
<h:outputText binding="#{linkedBean.composant}" />
Difference between attributes "value" and "binding" is that "value" only bind the value of component and "binding" bind the component instance. For example a text field accept a "String", a "Number" or a primitive as value. So attribute "value" must have the same type. A text field is represented by the class "HtmlInputText". The class hierarchy is:
Attribute "binding" can be any of these types. Unified Expression language Unified EL (Unified Expression Language) is language created to propose a simple way to access Java code from tags. This syntax has appeared with JSP 2.0 and JSF 1.0 under the name Expression Language. JSP and JSF used 2 differeents versions of EL. It?s only in JSP 2.1 and JSF 1.2 that the language has been unified under the name "Unified Expression Language". By default Servlet version 2.3 and previous ignore this syntax. It?s possible to change this behavior with the directive:
<%@ page isELIgnored ="true|false" %>
In JSP, a EL expression is like "${ }". In JSF we use "#{}". Without explain differences between these 2 syntaxes, remember that it?s generally bad to mix JSF and JSP EL expressions (like mixing AWT and Swing). The best way is to use only JSF syntax and replace JSP tags by their equivalents in Facelets tags (see chapter "9 Facelets").
Variables
It?s possible to reference any object in a page. For example:

#{person}
The Web (or Portlet) container will look for an object which is named "person" in the page, the request, the session or the application. "." Operator is used to access a property, method of an bean. For example to access "name" property of "person", you?ll write:
Page 58 of 100
17/10/09 18:17
#{person.name}
To access method "checkLogin" of "person":

#{person.checkLogin}
To access an array or a list, use operator "[]". Example, you want to get the third element of an array:
#{uelBean.tab[2]}
In this case expression "#{bean[property]}" is equivalent to "tab.get(index)". If exception IndexOutOfBoundsException is thrown, null is returned. For others exceptions, an error is returned. For Map, use expression "#{bean['key?]}" is equivalent to "bean.get(key)" or null if the Map doesn?t contains the key. For example, if you want to get the value mapped to the key "login":
#{uelBean.map['login']}
Operator "[]" can also be used to access property or method. In this case, the name of the property (or method) must be enclosed with quote. Examples: Access to property "name" of "person".
#{person['name']}
Which is equivalent to:

#{person.name}
Call to method "checkLogin" of "person".

#{person['checkLogin']}
Which is equivalent to:

#{person.checkLogin}
Implicit objects
They are implicits objects in JSF pages. They are always accessible with EL expression. Table 4. Object name cookie facesContext header headerValues initParam param paramValues requestScope sessionScope view Description A Map which map cookie values to a their values. Current FacesContext instance A Map which HTTP headers to their values. A Map which HTTP headers to String array. An array contains all values of a header. A Map which map init parameters to their values. A Map which map request parameters to their values. A Map which map request parameters to their values. An array contains all values of a parameter. A Map which map request attributes to their values. A Map which map session attributes to their values. Root component of a JSF page.
applicationScope A Map which map application attributes to their values.
Operators
Most of Java operators can be used. But you can also used Arithmetic: +, -, *, /,%, "div" and "mod". Logical: &&, ||, !, "and", "or" and "not". Relational: ==, "eq", !=, "ne", <, "lt", >, "gt", <=, "le", >=, "ge". These operators can compare primitives and String. Compound: expression ? val1 : val 2. instanceof "empty" test if a value is null or if an array or a list is empty.
JSF Taglibs
Now we will study some useful tag in a JSF page. Every JSF component (not HTML) is a tag which is prefixed by default with a "f". The tag?s name is the same as the component without the "UI" prefix. Every HTML component is a tag which is prefixed by a "h" by default. The tag?s name is the same as the component without the "Html" prefix.
JSF View
The first tag that we have to use in JSF is <f:view>, this tag permit to declare the view which will contains the others tags.
<f:view>  </f:view>
Simple text
The <f:verbatim> tag generate an UIOutput component from its content. It?s the simpler tag to display text, but it?s
Page 59 of 100

not a specific HTML tag. So it?s not possible to use every HTML attributes like the CSS style. Example:
<p> <f:verbatim>Hello Verbatim</f:verbatim> </p>
17/10/09 18:17
This example will generate this HTML code:

<p>Hello Verbatim</p>
Output components
The tags which permit to display some text are: <h:outputText> <h:outputFormat> <h:outputLabel> They correspond to the components: HtmlOutputText HtmlOutputFormat HtmlOutputLabel They inherit from UIOutput which implement ValueHolder.The "value" attribute permit to define the text to display. This attribute can be associated with a primitive, a String, a Number or every class which contains a data converter (Chapter "7.3 Conversions"). Simple text The simpler tag to display a text in one line is:
<p> <h:outputText value="text"/> </p>
This tag will generate this HTML code:

<p>text</p>
Here is an other example but this time we will include some text in the tag.
<p> <h:outputText value="Another test of " style="color: red"> outputText </h:outputText> </p>

<p>outputText <span style="color: red">Another test of </span></p>
Graphically you?ll have:
Note that the text in the tag is displayed before the text specify in the "value" attribute. Only the text write in the tag can us CSS style. Note : It?s possible to display a text from a resource file (Chapter "8.1 Internationalization). Formatted output The <h:outputFormat> tag displays a formatted message with the format() method from the MessageFormat class. It?s possible to transmit parameters on using under tag <f:param />. Example of JSF code :
<p> <h:outputFormat value="outputFormat is {0}"><br /> <f:param value="great" />  </h:outputFormat> </p>
This example generate this HTML code:

<p>outputFormat is great</p>
Other use:
<h:outputFormat value="Precision at 2 digit: {0,number,#.##}, at 1 digit: {0,number,#.#}"> <f:param value="#{basic.nb}" /> </h:outputFormat>
This example will display:

Precision at 2 digits: 4,15, at 1 digit: 4,2
For more information, look at the MessageFormat class documentation. Label The <h:outputLabel> tag represent the <label> tag on HTML. It permts to affect a label to a input component like text field or a checkbox. This tag is used like an under tag of the referenced tag. The "for" attribute contains the id of the right label. Example :
<h:inputText id="address " value="your address here"> <!?text field > <h:outputLabel for="address " value="Address:" />
Page 60 of 100
17/10/09 18:17
</h:inputText>

<label for="address">Address:</label> <input id="address" type="text" name="address" value="your address here" />
You can also use the <h:outputLabel> tag. Example :

<h:outputLabel for="city" value="City:" /> <h:inputText id="city" value="Strasbourg" />
Here is what it will display with the 2 examples :
Form
This tag represents a form. The component implements "NamingContainer". It means that every tags in a form must have an unique id. Example:
<h:form> </h:form>
JSF will add some information when the tag will be translated into HTML. The method used by the form is always "POST" and the encoding in " application/x-www-form-urlencoded".
<form id="_id0" method="post" action="/HW/04Form.jsf" enctype="application/x-www-form-urlencoded"> <input type="hidden" name="_id0" value="_id0" /> </form>
A last example which illustrate how to add an id for every under tags of a form:
<h:form> <h:outputText id="name" value="text" /> </h:form>
In HTML:
<form i d="_id1" method="post" action="/HW/04Form.jsf" enctype="application/x-www-form-urlencoded"> <span id="_id1:name">text</span> <input type="hidden" name="_id1" value="_id1" /> </form>
Every component which doesn?t have an id will have an attributed one. The id used is prefixed by the id of the form. It permits to give few times the same id in different form.
Input components
The components to type data: HtmlInputText HtmlInputTextarea HtmlInputSecret HtmlInputHidden They inherit of UIInput which implements EditableValueHolder. The "value" attribute of these tag permit to affect a value by default to a field. The value can be linked to a primitive, a String, a Number or every class which have a data converter. It?s possible to use "required" attribute to indicate that a field is obligatory. Text field The simpler tag to type text is <h:inputText>.
<h:inputText maxlength="20" size="20" value="default value"/>

<input type="text" value="default value" maxlength="20" size="20" />
Multi lines text field The <h:inputTextArea> tag permit to type a text in few lines.
<h:inputTextarea cols="10" rows="10" />
This example generate this HTML code:

<textarea cols="10" rows="10"></textarea>
Password field The <h:inputSecret> permit to type a password. The "redisplay" attribute permit to keep it when the page is reloaded. (By default its value is false).
<h:inputSecret redisplay="false" value="#{bean.password}" />
The JSF code generate this HTML code:

<input type="password" />
Hidden field
Page 61 of 100
17/10/09 18:17
The <h:inputHidden> tag permit to include a hided field in a web page.

<h:inputHidden value="#{bean.hide}"/>
This JSF code generate this HTML code:

<input type="hidden" value="value" />
Link
It exist 2 kind of link in JSF: The simple links, which don?t start any event on the server side. The link which will start an event on the server side. It will permit to manage the navigation of the web site with a unique file. Every links of your web site (which are linked to your web site) have to be the second type. With this kink of link you?ll be able to define the navigation of your web site in a configuration file. Simple link The <h:outputLink> tag permit to display a link. It uses the "HtmlOutputLink" component which inherits of UIOutput which implements ValueHolder. The "value" attribute permit to define the url of the link. The value can be associated to a primitive, a String, a Number or every class which have a data converter. It doesn?t exist attribute which define the text of the link. To define the text, we have to use an under tag like <h:outputText>. Example :
<h:outputLink value="url "> <h:outputText value="Text of the link" /> </h:outputLink>
We can use few under tags to define the text:

<h:outputLink value="url "> <h:outputText value="Text " /> <h:outputText value="of the " /> <h:outputText value="link" /> </h:outputLink>
In the 2 cases, the HTML code will be:

<a href="url">Text of the link</a>
Every urls are relatives to the current url. It?s possible to refer to the web site root on prefixing the url by "/". If we have the following url:
http://localhost:8080/JSFCours/faces/testLiens.jsp
Where " JSFCours " is the web site context and " faces " is JSF file mapping. So, for example : " index.jsp " is reachable through the url " http://localhost: 8080/JSFCours/faces/index.jsp " " /index.jsp " is reachable through the url " http://localhost:8080/index.jsp " It is possible to retrieve the web site context and mapping with the following expressions: #{facesContext.externalContext.requestContextPath}, web site context #{facesContext.externalContext.requestServletPath}, mapping to the JSF Servlet. This string is empty if mapping use a suffixe (like *.jsf). #{facesContext.externalContext.requestPathInfo}, path to the current web page, starting from the JSF Servlet. For example, if you have the URL " http://localhost:8080/JSFCourse/faces/testLiens.jsp " so you will retrieve the following values: facesContext.externalContext.requestContextPath = /JSFCourse facesContext.externalContext.requestServletPath = /faces facesContext.externalContext.requestPathInfo = /testLiens.jsp JSF link You can create a link with " HtmlCommandLink ". It extends UICommand which implement " ActionSource ". The tag related to this component is <h:commandLink>. This tag has to be nested inside a <h:form> tag. Its " value " attribute allows to define its text (not destionation URL). The value can either be a primitive, a String, a Number or any other class with a converter (see chapter about converters). This kind of link does not use any URL to define destionation, but a string value. This one is evaluated inside JSF navigation rules which are defined inside its configuration (see faces-config.xml file). See chapiter " 6.2 Navigation " for further information about the action attribute and navigation rules. Exemple :
<h:form> <h:commandLink action="success" value="This is a JSF link" /> </h:form>
If no action attribute is defined, the link refreshes the current page. It is also possible to nest a <h:outputText> tag to define the displayed text:
<h:form>
Page 62 of 100
17/10/09 18:17
<h:commandLink action="success"> <h:outputText value="This is a JSF link" /> </h:commandLink> </h:form>
The two previous example render the following HTML code:

.. <form method="post" action="/HW/06Liens.jsf" enctype="application/x-www-form-urlencoded"> <a href="#">lien success</a> </form> ...
Parameters It is possible to define parameters inside a link by nesting <f:param> tags. It has two main attributes, which are " value " and " name " :
<h:form> <h:outputLink value="index.jsp"> <h:outputText value="index.jsp"/> <f:param name="id" value="2"/> <f:param name="sortBy" value="price"/> </h:outputLink> <br/> <h:commandLink> <f:param name="id" value="6"/> <f:param name="sortBy" value="name"/> </h:commandLink> </h:form>
They can be retrieved with the expression " #{param.ParameterName} ". In this case, it is :
<h:outputText value="id=#{param.id}, sortBy=#{param.sortBy}" />
You can test wether the parameter has been defined with the expression: " #{!empty param.ParameterName} ". It allows defining tags only if a parameter exists. Example:
<h:outputText value="(Only displayed if 'id' exists) id=#{param.id}" rendered="#{!empty param.id}"/>
Button
The component which display a button is " HtmlCommandButton ". It extends UICommand which implements ActionSource (and ActionSource2 for JSF 1.2). A button works almost like link. Example :
<h:form> <h:commandButton action="action value" value="Send" /> </h:form>
Below is the returned HTML code:

<input type="submit" value="Send" />
Checkbox
There are 2 components which display checkboxes: <h:selectBooleanCheckbox> only one checkbox <h:selectManyCheckbox> many checkboxes. BooleanCheckbox Component The " value " attribute define wether the checkbox is displayed (or not). It can only be a boolean value. Example:
<h:selectBooleanCheckbox id="choice" value="#{bean.property}"/>
Returned HTML code:

<input id="choix" type="checkbox" />
To display a text close to the checkbox, you have to nest a <h:outputLabel> tag. Example:
<h:selectBooleanCheckbox id="choice" value="#{bean.property}"> <h:outputLabel for="choice" value="Married :" /> </h:selectBooleanCheckbox>
ManyCheckBox component Most of the time, you want to display many checkboxes in the same time to propose many choices. You have to use the <h:selectManyCheckbox> tag. It has a " layout " attribute which allow displaying value either: Horizontal side with " lineDirection " value Vertical side with " pageDirection " value. Selected boxes can be saved inside a List or Array object. It is referenced by the "value" attribute. You can also define inside which boxes are selected by default (you will see that later). In order to define which boxes have to be displayed, you have either to: nest <f:selectItem> tags or nest a single <f:selectItems> tag which need a reference with items from the managed-bean.
SelectItem
Page 63 of 100

The nested <f:selectItem> tag is a check box. Its attributes " itemValue " and " itemLabel " contain the value and the displayed text. Example:
<h:selectManyCheckbox id="ville" layout="pageDirection" value="#{bean.selectedCities"> <f:selectItem itemValue="StrasValue" itemLabel="Strasbourg" /> <f:selectItem itemValue="LyonValue" itemLabel="Lyon" /> <f:selectItem itemValue="ParisValue" itemLabel="Paris" /> </h:selectManyCheckbox>
17/10/09 18:17
It displays the following french cities:
Below is the ManagedBean code:

public class Bean { private List selectedCities = new ArrayList(); public List getSelectedCities() { return selectedCities; } public void setSelectedCities(List selectedCities) { this.selectedCities = selectedCities; } }
Here, items value is " java.lang.String ". " #{bean.selectedCities} " expression create a link with the selected cities. Its contains the "itemValue" of all the selected boxes. For example, when the user sends a form with the " Strasbourg " city selected, thus " selectedCities " will contain " StrasValue ". If the user selects 2 boxes, " selectedCities " will contain " StrasValue " and " LyonValue ". It is important to take care about the type of your objects on the ManagedBean side. Indeed, you can either use an array of String (String []) or a List to contains selected cties, but you can not use an array of integer because values are strings. If you want to create items with objects of your choice (like your own class City), you have to use a converter. Indeed, JSF need a String value.
SelectItems
You can also initialize your items directly from a ManagedBean containing an Array, a Map or a List. Let?s take the following class as ManagedBean:
public class Bean { private List selectedCities = new ArrayList(); private List allCities = new ArrayList(); public Bean() { //add available cities allCities.add(new SelectItem("StrasbourgValue", "Strasbourg :")); allCities.add(new SelectItem("LyonValue", "Lyon :")); //city selected by default selectedCities.add("LyonValue"); } public List getAllCities() { return allCities; } public void setAllCities(List allCities) { this.allCities = allCities; } public List getSelectedCities() { return selectedCities; } public void setSelectedCities(List selectedCities) { this.selectedCities = selectedCities; } }
Then you reference your ManagedBean inside a <f:selectItems> tag:

<h:selectManyCheckbox id="ville" value="#{bean.selectedCities}"> <f:selectItems value="#{bean.allCities}" /> </h:selectManyCheckbox>
You can also use an array to save your cities:

SelectItem[] allCities ;
Finally, you can use a Map. In this case, the keys are the values, and values of the map are the displayed labels. Example:
Map allCityMap = new HashMap(); allCitiesMap.put("Strasbourg :", "StrasbourgValue "); allCitiesMap.put("Lyon :", "LyonValue ");
How to gather items?
It is possible to create SelectItem groups, by using the <f:selectItems> tag. You have to put your items inside a SelectItemGroup. Its constructor has the following parameters: Group name Description Activation (false means disabled and true means enabled) A SelectItem array Once a SelectItemGroup instanciated, you can gather many groups and items inside a List as you can see on the following example:
Page 64 of 100
17/10/09 18:17
// city list List allCities = new ArrayList(); //french cities SelectItem[] citiesFrance = new SelectItem[3]; citiesFrance[0] = new SelectItem("StrasValue", "Strasbourg"); citiesFrance[1] = new SelectItem("LyonValue", "Lyon :"); citiesFrance[2] = new SelectItem("ParisValue", "Paris :"); //create a group for French cities SelectItemGroup franceGroup = new SelectItemGroup("France", "French cities", false, citiesFrance); //german cities SelectItem[] germanyCities = new SelectItem[2]; germanyCities[0] = new SelectItem("KehlValue", "Kehl :"); germanyCities[1] = new SelectItem("BerlinValue", "Berlin :"); // create a group for german cities SelectItemGroup germanyGroup = new SelectItemGroup("Allemagne", "German cities", false, germanyCities); SelectItem london = new SelectItem("LondresValue", "Londres :"); allCities.add(franceGroup); allCities.add(london); allCities.add(germanyGroup);
It displays the following page:
RadioButton
The <h:selectOneRadio> tag allows defining a radio button list. It use the class " HtmlSelectOneRadio " which implement " EditableValueHolder ". A list is constructed with nested <f:selectItem> tags or a single <f:selectItems> tag (see chapter " 5.8.2 MultipleCheckbox component " for more information about these tags). Notice that only one button can be selected at the same time. The radio button selected can either be stored as a primitive, a String, a Number or any class having a converter. Example:
<h:selectOneRadio layout="lineDirection" value="#{bean.color}> <f:selectItem itemValue="red" itemLabel="red"/> <f:selectItem itemValue="white" itemLabel="white"/> <f:selectItem itemValue="yellow" itemLabel="yellow"/> </h:selectOneRadio>
The property referenced by the " value " attribute should have the same type as the item value. Above, " #{bean.color} " is a String because values are Strings.
List
There is 2 components to display a list: <h:selectOneListbox> to display a list with only one item selected in the same time (it works the same way as <h:selectOneRadio>). <h:selectManyListbox> display a multiple choice list (it works the same way as <h:selectManyCheckBox>). The " size " attribute allows you to define how many lines you want to display. Example:
<h:selectManyListbox id="color" value="#{bean.colors}"> <f:selectItem itemValue="red" itemLabel=" Red:"/> <f:selectItem itemValue="white" itemLabel=" White:"/> <f:selectItem itemValue="yellow" itemLabel=" Yellow:"/> </h:selectManyListbox>
Below is the result:

<select id="color" size="3"> <option value="rouge">Red:</option> <option value="blanc">White:</option> <option value="jaune">Yellow:</option> </select>
Combo Box
A Combo box is created by the <h:selectOneMenu> tag. It is very similar as <h:selectOneRadio> tag (see chapter " 5.9 RadioButton " for further information). Example:
<h:selectOneMenu id="city" value="#{bean.selectedCities}"> <f:selectItems value="#{bean.allCities}" /> </h:selectOneMenu>
Pictures
Page 65 of 100

The <h:graphicImage> tag allows to insert a picture. It has the following attributes: " url ", the path to the picture " alt ", a description of the picture
<h:graphicImage url="URL to the picture" alt="description"/>
17/10/09 18:17
You can also use pictures as links by nesting a <h:graphicImage> tag inside a link component:
<h:outputLink value="http://java.net"> <h:graphicImage value="javadotnet.jpg" /> <h:outputText value="java.net" /> </h:outputLink>

<a href="http://java.net"><img src="java.jpg" alt="" />java.net</a>
Panel
The <h:panelGroup> tag allows gathering many JSF components in order to handle them as only one tag. Indeed, some components can only have one nested tag. Example:
<h:panelGroup> <h:outputText value="first child" /> <f:verbatim><br /></f:verbatim> <h:outputText value="second child" /> </h:panelGroup>
It returns the following HTML code:

first child<br />second child
Notice the <f:verbatim> tag around <br/>. It allows returning the text and tags in the same postition. Indeed, if you do not use it...:
<h:panelGroup> <h:outputText value="first child" /> <br /> <h:outputText value="second child" /> </h:panelGroup>
You could have the following result:

<br />first childsecond child
Table
There is two ways to create tables with JSF: <h:panelGrid> <h:dataTable> They both have the following attributes: footerClass: define which CSS class(es) are used to display the table?s footer headerClass: define which CSS class(es) are used to display the table?s header captionClass (only with JSF 1.2): The " columnClasses " attribute allows defining CSS style listing for each column. In order to define CSS classes for a column, you have to put a space between each one:
class1.1 class1.2 class1.3 ...
To declare CSS classes for each column, you have to use a comma:
class1.1 class1.2 class1.3, class2 class2.1, class3, class4 class4.1 class 4.2
In this case, the table... has 4 columns CSS classes " class1.1 ", " class1.2 " and " class1.3 " are used for the first column " class2 " and " class2.1 " for the second " class3 " for the third " class4.1 " and " class4.2 " for the fourth. If there is not the same number of CSS classes groups and columns: If there are more columns than CSS classes groups, then CSS classes groups are reused for the following columns. If there are less columns than CSS classes groupes, useless CSS classes groups won?t be used. The " rowClasses " attribute allows defining CSS classes to lines, and it works the same way. Static table: PanelGrid This kind of array is created with the <h:panelGrid> tag. When you use this table, it means you already know how many lines and rows you want to display. Indeed, it does not fit well with dynamically generated tables.
Page 66 of 100

In order to define the content of a table, you have to nest tags inside. Example:
<h:panelGrid border="1" columns="2"> <h:outputText value="A" /> <h:outputText value="B" /> <h:outputText value="C" /> <h:outputText value="D" /> </h:panelGrid>
17/10/09 18:17
We described the cells starting from upper left to bottom right. There is no tag which defines the beginning or the end of a line. JSF define the position of each component according the order in which it is declared. As there are 2 columns, and 4 components, we can assume there is 2 lines. It displays the following table: Table 1. A B C D
Now, if you want to display 3 columns, a new line will be created for each after 3 tags:
<h:panelGrid border="1" columns="3"> <h:outputText value="A" /> <h:outputText value="B" /> <h:outputText value="C" /> <h:outputText value="D" /> </h:panelGrid>
It displays the following table: Table 2. A B C D
Group elements
If you want to use many tags inside the same cell, you have to group them inside the <h:panelGroup> tag. Example:
<h:panelGrid columns="2" border="1" rules="all"> <h:outputText value="A" /> <h:panelGroup> <h:outputText value="B" /> <f:verbatim><br /></f:verbatim> <h:outputText value="B bis" /> </h:panelGroup> <h:outputText value="C" /> <h:outputText value="D" /> </h:panelGrid>
The following code is generated:

<table border="1" rules="all"> <tbody> <tr> <td>A</td> <td>B<br />B bis</td> </tr> <tr> <td>C</td> <td>D</td> </tr> </tbody> </table>
Header and footer
A header or a footer is defined with a <f:facet> tag. It has an attribute called " name " which define which part is currently written. Available values are the following ones: " header ", if it is a header " footer ", if it is a footer " caption ", if it is a title (only with JSF 1.2) The <f:facet> tag do not have any child tag, you have to use the <h:panelGroup> tag to nest many tags. Example:
<h:panelGrid border="1" columns="2" rules="all"> <f:facet name="header"> <h:outputText value="I am the header!" /> </f:facet> <f:facet name="footer"> <h:panelGroup> <h:outputText value="I am the " /> <h:outputText value="footer" /> </h:panelGroup> </f:facet>  <f:facet name="caption">
Page 67 of 100
17/10/09 18:17
<h:outputText value="caption" /> </f:facet> <h:outputText value="A" /> <h:outputText value="B" /> <h:outputText value="C" /> <h:outputText value="D" /> </h:panelGrid>
Below is the returned HTML code:

<table border="1" rules="all"> <thead> <tr> <th colspan="2" scope="colgroup">I am the header </th> </tr> </thead> <tfoot> <tr> <td colspan="2">I am the footer</td> </tr> </tfoot> <tbody> <tr> <td>A</td> <td>B</td> </tr> <tr> <td>C</td> <td>D</td> </tr> </tbody> </table>
Below is a screenshot
Dynamic table: DataTable The <h:dataTable> tag allows to generate a table dynamicaly. Indeed, it browses elements like the following ones: A JavaBean list A JavaBean array A JavaBean A javax.faces.model.DataModel A java.sql.ResultSet A javax.servlet.jsp.jstl.sql.ResultSet A javax.sql.RowSet The " value " attribute allows defining which property to browse. Furthermore, " var " attribute is the name which references the elements of the " value " attribute. Below is an example:
<h:dataTable value="#{bean.elementList}" var="itemFromTheList" />
To define the content of the table, you have to use the <h:column> tag. Each one set a new column :
<h:dataTable value="#{bean.elementList}" var="itemFromTheList" /> <h:column> <%--first column--%> <h:outputText value="#{itemFromTheList .property1" /> </h:column> <h:column> <%--second column--%> <h:outputText value="#{itemFromTheList .property2}" /> </h:column> </h:dataTable>
If the list contains five elements, thou the table display five lines. You can also use the following attributes: " first " to define the first displayed element " rows " to define how many elements to display
Header and Footer
Like PanelGrid table, headers, footers and titles are defined with <f:facet> tag by nested the <f:facet> tag inside a <h:column> tag. Example:
<h:dataTable id="items" value="#{bean.myList}" var="item"> <h:column> <f:facet name="header"> <h:outputText value="Property 1" />
Page 68 of 100
17/10/09 18:17
</f:facet> <h:outputText value="#{item .property1 }" /> </h:column> <h:column> <f:facet name="header"> <h:outputText value="Property 2" /> </f:facet> <h:outputText value="#{item .property2 }" /> </h:column> <f:facet name="footer"> <h:outputText value="I am a footer!"/> </f:facet> </h:dataTable>
Example: Display a database table
Let?s finish by an exemple which display a database table inside a JSF table ! We start by writing a JavaBean which read the database content. Indeed, when an instance is created, a simple " SELECT " request is executed over a table. Then we will display it inside a <h:dataTable> tag. Example:
package com.labosun; public class DataBaseBean { private ResultSet personRS; public DataBaseBean() { initConnection(); } //Getter and setter public ResultSet getPersonRS() { return personRS; } public void setPersonRS(ResultSet personRS) { this.personRS = personRS; } private void initConnection() { try { Class.forName("com.mysql.jdbc.Driver").newInstance(); Connection cnx = DriverManager.getConnection("jdbc:mysql://localhost/jsfCours", "login", "pass"); Statement st = cnx.createStatement(); this.personRS = st.executeQuery("select * from contact"); } catch (Exception e) { // exception handling (not described here) } } }
Here we declare a bean, inside the JSF "faces-config.xml" configuration file:

<managed-bean> <managed-bean-name>dbBean</managed-bean-name> <managed-bean-class>com.labosun.DataBaseBean</managed-bean-class> <managed-bean-scope>request</managed-bean-scope> </managed-bean>
Then, the following JSF code uses the ResultSet with <h:dataTable> tag and its "value" attribute:
<h:dataTable value="#{dbBean.personRS}" var="personDB" rules="all" border="1"> <h:column> <f:facet name="header"> <h:outputText value="Name" /> </f:facet>  <h:outputText value="#{personDB['lastName']}" /><br /> </h:column> <h:column> <f:facet name="header"> <h:outputText value="Prnom" /> </f:facet>  <h:outputText value="#{personDB.firstName}" /> </h:column> </h:dataTable>
Error messages
When an error append (empty text field, conversion error, etc.) a message is created. It is displayable inside with <h:message> and <h:messages> tags. This feature is described in the chapter " 8.2 Messages management ". For the moment, we will only see to display them. Messages have different importance levels: " SEVERITY_INFO ", information message (low importance) " SEVERITY_WARN ", warning message " SEVERITY_ERROR ", error message " SEVERITY_FATAL ", fatal message (high importance) There are 2 kinds of message, which are either specific or global: The <h:message> tag display a message. It?s " for " attribute allows defining which comonent it is related to. The <h:messages> tag allows displaying all the messages. These tags have the two following attributes: Table 3. Attribute Type Default value Description
Page 69 of 100

showDetail boolean false Define wether more information is displayed. Define wether a summary is displayed.
17/10/09 18:17
showSummary boolean true
The <h:messages> tag has also the following ones: Table 4. Attribute Type Default value Description Define wether the tag display only global messages (true) or all the messages (false). It allows defining a specific renderings: layout String list " list " to display messages in a HTML list " table " to display messages in a HTML table
globalOnly boolean false
Example:
<h:inputText id="number"> <f:validateLongRange minimum="1" maximum="10" /> </h:inputText> <h:message for="number"/> <h:commandButton id="submit" action="success"/>
The <f:validateLongRange> tag allows testing if value is between 1 and 10. Indeed a message is displayed if the value is not validated. You can also change the CSS class of your messages : Table 5. Name Description
errorClass CSS class used for " ERROR " level messages. fatalClass CSS class used for " FATAL " level messages. infoClass CSS class used for " INFO " level messages. warnClass CSS class used for " WARN " level messages.
There is also the " errorStyle ", " fatalStyle ", " infoStyle " and " warnStyle " attributes to define directly the style.
Server configuration
JSF configuration is set into the " WEB-INF/faces-config.xml " file. The template of this file is:
<?xml version="1.0"?> <!DOCTYPE faces-config PUBLIC "//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN" "http://java.sun.com/dtd/web-facesconfig_1_1.dtd"> <faces-config> </faces-config>
With JSF 1.2, the file looks like this:

<?xml version='1.0' encoding='UTF-8'?> <faces-config xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd" version="1.2"> </faces-config>
Nested tags allow configuring JSF.
JavaBeans declaration
To configure JavaBeans and handle them through JSF pages, below is the appropriate declaration:
<managed-bean> <managed-bean-name>nom du bean dans la page JSF</managed-bean-name> <managed-bean-class>class du bean </managed-bean-class> <managed-bean-scope>(application|session|request|none)</managed-bean-scope> <managed-property> <property-name>nom de la proprit </property-name> <property-class>type de la proprit </property-class> <value>valeur par dfaut </value> </managed-property> </managed-bean>
" managed-bean-name " is the JavaBean name to reference it from JSF pages. " managed-bean-class " is the fully qualified name of the JavaBean class. " managed-bean-scope " define the scope of your JavaBean (either request, session, application or none). " managed-property " initialize a property of your managed bean. Available scope values are the following: " application " means your JavaBean instance is reachable for all the users.
Page 70 of 100

" session " means your JavaBean instance is specific for each user. " request " means a JavaBean instance is created for each request. " none " means a JavaBean instance is created each time it is called. List declaration A list is declared with the <listentries> tag. Then you nest values with <value> tags. Example:
<managed-bean> <managed-bean-name>cityList</managed-bean-name> <managed-bean-class>java.util.ArrayList</managed-bean-class> <managed-bean-scope>application</managed-bean-scope> <list-entries> <value-class>java.lang.String</value-class> <value>Strasbourg</value> <value>Bordeaux</value> <value>Paris</value> <value>Nice</value> <null-value/> </list-entries> </managed-bean>
17/10/09 18:17
Notice you can include a null value thank to the <null-value> tag. You can also define which class to use with the <value-class> tag. Map declaration A "Map" is declared with a <map-entries> tag. For each entry in the map, you have to insert a <map-entry> tag. This last one has two nested elements which are <key> and <value>. Example:
<managed-bean> <managed-bean-name>dicoMap</managed-bean-name> <managed-bean-class>java.util.HashMap</managed-bean-class> <managed-bean-scope>application</managed-bean-scope> <map-entries> <key-class>type.of.your.class</key-class> <value-class>type.of.your.value</value-class>  <map-entry> <key>value of the key 1</key> <value>value associatied with key 1</value> </map-entry>  <map-entry> <key>value of the key 2</key> <value>value associated with key 2</value> </map-entry> </map-entries> </managed-bean>
Just as list declaration, you can define which class to use. The <key-class> and <value-class> tags define which class to use as key and value. They are both nested inside the <map-entries> tag. Finally, it is possible to define a null value with the <null-value> tag. Example: Declaration of a SelectItem list We already have declared collections, ... now, let?s see about SelectItem list. We first created managed beans with the SelectItem class and entries within:
 <managed-bean> <managed-bean-name>city0</managed-bean-name>  <managed-bean-class>javax.faces.model.SelectItem</managed-bean-class> <managed-bean-scope>application</managed-bean-scope>  <managed-property> <property-name>value</property-name> <value>Stras</value> </managed-property> <managed-property> <property-name>label</property-name> <value>Strasbourg</value> </managed-property> </managed-bean>  <managed-bean> <managed-bean-name>city1</managed-bean-name> <managed-bean-class>javax.faces.model.SelectItem</managed-bean-class> <managed-bean-scope>application</managed-bean-scope> <managed-property> <property-name>value</property-name> <value>Lyon</value> </managed-property> <managed-property> <property-name>label</property-name> <value>Lyon</value> </managed-property> </managed-bean>
Then you declare another managed bean with the ArrayList class and entries made of previously declared "city0" and "city1" managed beans.
Page 71 of 100
17/10/09 18:17
 <managed-bean> <managed-bean-name>villes</managed-bean-name> <managed-bean-class>java.util.ArrayList</managed-bean-class> <managed-bean-scope>application</managed-bean-scope> <list-entries> <value-class>javax.faces.model.SelectItem</value-class> <value>#{city0}</value> <value>#{city1}</value> </list-entries> </managed-bean>
As you can see, this syntax is a bit heavy, and it is shorted to write entries directly.
Navigation
Navigation is defined with "navigation rules". Each rules define sources and destinations pages.
<navigation-rule> <from-view-id>/source page</from-view-id> <navigation-case> <from-outcome>string returned by an action</fromoutcome> <to-view-id>/destination page</to-view-id> </navigation-case> </navigation-rule>
The " from-view-id " tag defines the source page. Then we can nest as many " navigation-case " as needed and each one have an "outcome" string and "destination" page. The " from-outcome " tag is the string returned by a link, a button, a managed bean method, etc. Finally the " to-viewid " tag is the destination page. Take the following example:
<navigation-rule> <from-view-id>/index.jsp</from-view-id> <navigation-case> <from-outcome>success</from-outcome> <to-view-id>/buy.jsp</to-view-id> </navigation-case> </navigation-rule>
As you can see above, you are creating a navigation rule for the web page "index.jsp". If an action return the value "success", then the user is being forwarded to " buy.jsp ". You have to use "/? as the beginning of the URL to refer to the root of the web site. You can insert actions into your web pages with JSF tags and their "action" attribute:
Action example with a link: <h:form> <h:commandLink action="success" value="Make an order"/> </h:form> Action example with a button: <h:form> <h:commandButton action="success" value="Make an order"/> </h:form>
Notice that this declaration works well with the two following JSF declaration, inside "web.xml" file:
<servlet-mapping> <servlet-name>Faces Servlet</servlet-name> <url-pattern>/faces/*</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>Faces Servlet</servlet-name> <url-pattern>*.jsf</url-pattern> </servlet-mapping>
Let?s now explore a bit more use cases. Global mapping It is also possible to define a navigation rule for all your application with the "/*" value as source value. Example:
<navigation-rule> <from-view-id>/*</from-view-id> <navigation-case> <from-outcome>error</from-outcome> <to-view-id>/error.jsp</to-view-id> </navigation-case> </navigation-rule>
In this case, all the pages which returns "error" shall forward the user to the web page "error.jsp". Another solution is to remove the <from-view-id> tag. Action strings Let?s look a bit further about navigation. There is two main tags, which are <from-action> and <from-outcome>. They can be used alone or in the same time. Indeed there is three ways to declare navigation rules: If you only write out the " from-outcome " tag, the string must be equal either to an action attribute value or the return value of a method. If you write out the two of them, naviguation would only be true if the method defined inside " from-action " returns the value specified inside the " from-outcome " tag. If you only write out the " from-action " tag, the value should be a reference to a method. Whatever the return value is, navigation is true.
Page 72 of 100

Currently used action strings in " from-outcome " are the following: Table 1. Outcome success failure logon It worked correctly Error during page rendering User should be redirected to login page. Signification
17/10/09 18:17
no results Research did not return any result. Return to the search form.
From-outcome
It is the tag we used in the previous examples. You can also call a method from a managed-bean and analyse its return value. Below is a method example:
public String methodName();
Then, write out the following component:

<h:commandLink action="#{bean.method}" value="Vers la page xxx"/>
Let?s take a full example ? first we define the following rule:

<navigation-rule> <from-view-id>/index.jsp</from-view-id> <navigation-case> <from-outcome>success</from-outcome> <to-view-id>/achat.jsp</to-view-id> </navigation-case> </navigation-rule>
... then a method from a managed-bean returns " success ".

public class NaviBean { public String getSuccessString() { return "success"; } }
... and finally we write out the JSF link component in the page " index.jsp ":
<h:form> <h:commandLink value="Vers la page achat" action="#{navi.getSuccessString}"/> </h:form>
Notice: "navi" is the name of our managed-bean.

From-action and from-outcome
Let?s illustrate " from-action " and " from-outcome " with the following example:
<navigationrule> <from-view-id>/index.jsp</from-view-id> <navigation-case> <from-action>#{navi.validateOrder} </from-action> <from-outcome>order</from-outcome> <to-view-id>/order.jsp</to-vie-wid> </navigation-case> <navigation-case> <from-action>#{navi.validateOrder} </from-action> <from-outcome>mustLogin</from-outcome> <to-view-id>/login.jsp</to-view-id> </navigation-case> </navigation-rule>
We used <from-action> twice but the value nested inside <from-outcome> will allow to create different navigation cases. If the method returns any other string than "order" or "mustLogin", the user is not redirected and he stays on the same page. In order to use this navigation case, you have to use an action attribute with a reference to a method, like displayed below:
<h:commandLink value="Valide les achats" action="#{navi.validateOrder}"/>
Here a example of method you could write:

public class NaviBean { public String valideAchat() { Random r = new Random(); int choice = r.nextInt(2); if( choice == 0) { return "order"; } else { return "mustLogin"; } } }
From-action
With this tag, you only specify which method to use:

<navigation-rule> <from-view-id>/index.jsp</fro-mview-id> <navigation-case>
Page 73 of 100
17/10/09 18:17
<from-action>#{navi.validateOrder}</from-action> <to-view-id>/order.jsp</to-view-id> </navigation-case> </navigation-rule>
Above, whatever the return value is, the user returns to the "order.jsp" page. Below is an action attribut which call the validateOrder() method:
<h:commandLink action="#{navi.valideOrder}" />
Example Let?s finish this chapiter by a comprehensive example of navigation rules. The purpose of the following web site is to manage a list. Indeed you have to write a managed-bean with a List<String> typed object. This web site is composed of the following pages: " list.jsp " is the main page, it displays all the entries of the list. It also displays links to remove and modify them. " detail.jsp " displays all the information of an entry. It also displays links to the list and delete page. " delete.jsp " allows to remove an entry, it displays a confirmation message and redirect the client to the list page. " new.jsp " allows to create a new entry inside the list. Elle possde un lien vers la page principale. When you want to remove an entry, you have to pass the entry parameter inside the request, as you saw on the chapter " 5.6.3 Parameters ". Below are navigation rules:
<navigation-rule> <from-view-id>/list.jsp</from-view-id> <navigation-case>  <h:messages /> <h:dataTable value="#{naviEx.elements}" var="elt" rules="all" border="1"> <h:column> <f:facet name="header"> <h:outputText value="Name" /> </f:facet> <h:outputText value="#{elt}" /> </h:column> <h:column>  <h:commandLink value="Delete" action="delete">  <h:commandLink value="edit" action="edit">  <f:param name="idElt" value="#{elt}" /> </h:commandLink> </h:column> </h:dataTable> <h:commandLink value="Create a new entry" action="new" /> </h:form> </f:view>
You can see below its display:
" edit.jsp " page:

<f:view> <h:form>  <h:outputText value="More information about #{param['idElt']}" /><br /> <h:commandLink value="Remote this entry" action="delete"> <f:param name="idElt" value="#{param['idElt']}" /> </h:commandLink> <h:commandLink value="Return and cancel" action="list" /> </h:form> </f:view>
Page 75 of 100
17/10/09 18:17
" new.jsp " page:

<f:view> <h:form> <h1>New entry</h1> <h:inputText id="name" value="#{naviEx.newElt}"> <h:outputLabel for="name" value="Name:" /> </h:inputText> <h:commandButton value="Validate" action="#{naviEx.create}" /><br /> <h:commandLink value="Cancel" action="success" /> </h:form> </f:view>
Below is the rendering:
" delete.jsp " page:

<f:view> <h:form>  <h:outputText value="Do you want to remove the entry: #{param['idElt']} ?" /> <h:commandLink value="Yes" action="#{naviEx.delete}">  <f:param name="idElt" value="#{param['idElt']}" /> </h:commandLink> <h:commandLink value="No" action="success" /> </h:form> </f:view>
Context parameters
You can configure JSF through its context parameters in the "web.xml" file.
<context-param> <param-name>Parameter name</param-name> <param-value>Parameter value</param-value> </context-param>
Below are common parameters: Table 2. javax.faces.CONFIG_FILES javax.faces.DEFAULT_SUFFIX javax.faces.LIFECYCLE_ID Define which files, separated by a comma, configure the JSF container. By default, JSF only look inside the " faces-config. xml " file. Default extension of JSF pages. By default, the value is " .jsp " Allows to define which class manage the life cycle of JSF. The default value is: LifecycleFactory.DEFAULT_LIFECYCLE Allows to define which facility save data. There are two available values: javax.faces.STATE_SAVING_METHOD " server ", data is saved inside the user session " client ", data is saved on the client side, as hidden fields. The default value is " server ".
Behavior
ActionListener
All the components which implement "ActionSource" (UICommand) can generate an event. This means a method is called when the user clicks on an element. The event is treated server side, when the client sends the page to the server. Here for recall the cycle of life of a JSF request :
The events of type ActionListener are treated during the phase "Invocation of the application". If the component which declares the event has the attribute "immediate" set to true, the event is treated during the phase "Request parameters appliction". Attention however, because during this phase, all the elements are not yet up to date (the javabeans are only updated during the phase "Update model"). The elements update order is the order of the tag declaration. There are 2 manners of dealing with server side events. The first solution is to associate a method of a generic JavaBean. Second is to create an implementation of the interface "ActionListener". Generic method
Page 76 of 100

To create a method which manages an event, it is necessary that it has the following prototype :
public void methodName(javax.faces.event.ActionEvent e);
17/10/09 18:17
The method can be in any bean, but it must be referred as a managed bean by the container. To use the method you only have to refer to it by using the attribute "actionListener". Example:
<h:commandButton value="Send" actionListener="#{beanName.methodName}" />
ActionListener interface It is also possible to create a class which implements "javax.faces.vent.ActionListener". There is just the method "processEvent (ActionEvent)" to implement. Example:
package listeners; public class EventHandling implements ActionListener { public void processAction(ActionEvent actionEvent) { // Event handling } }
This ActionListener can be referred in 2 different ways. It is possible to use the attribute "actionListener" as mentioned previously. But we can also use the tag <f:actionListener>. The "type" attribute of this tag makes it possible to specify the class of the used ActionListener. Example:
<h:commandLink value="with an interface"> <f:actionListener type="listeners.EventHandling" /> </h:commandLink>
ValueChange Listener
The components which implement "EditableValueHolder", i.e. all the child classes of UIInput (UISelectBoolean, UISelectMany, UISelectOne) have a value which can be edited by the user. When the page is sent to the server, all the modified values are generating a server side event. The management of this event is similar to ActionListener. Here for recall the cycle of life of a JSF request:
The events of type ValueChangeListener are treated during the phase "Validation of the user entries". If the component which declares the event has the attribute "immediate" set to true, the event is treated during the phase "Request parameters application". In that case, all the conversion operations and validations related to this component will be carried out before the ValueChangeListener management. Be careful however, because during this phase, not all the elements are yet up to date (the javabeans are only updated during the phase "model update"). The elements update order is the order of the tag declaration. Generic method A method which manages the event must have the following prototype:
public void check(javax.faces.event.ValueChangeEvent event);
The JavaBean which declares the method must be referred as JavaBean managed by the container. The method can then be referred thanks to the attribute "valueChangeListener".
<h:inputText valueChangeListener="#{beanName.methodName}" />
ValueChangeListener Interface The other solution consists in implementing "javax.faces.vent.ValueChangeListener" and to redefine the method "processValueChange (ValueChangeEvent)". Example :
package listeners; public class BeanValueChangeListener implements ValueChangeListener { public void processValueChange(ValueChangeEvent event) { // event handling } }
This listener can be referred either thanks to the attribute "valueChangeListener" as seen previously, either thanks to the tag <f:valueChangeListener>. The "type" attribute of this one makes it possible to specify the class of the used listener. Example:
<h:inputText value="value"> <f:valueChangeListener type="listeners.BeanValueChangeListener" /> </h:inputText >
Data conversion
The JSF components which implement ValueHolder (all the child classes of UIOutput) have a value. This value can be a date, a number, an email, ? There are no restrictions on the value which can be associated to a component under condition that the value can be converted form an Object into a String and conversely. This transformation is necessary,
Page 77 of 100

because during the phase "Request parameters application", the JSF Servlet must be able to rebuild the object which represents the value of the client request (which is in the form of a String). Then, at the time of the return phase, the object must be translated into a String. JSF manages the conversion of the primitives and the standard objects of Java: Boolean, Number All the conversion operations are carried out at the time of the phase "Request parameters application".
17/10/09 18:17
This principle of conversion also makes it possible to personalize the posting of the objects. For example a date canbe posted in the format "DD/MM/AAAA" or with the day in full letters. The conversions errors can be posted with the tag <h:message>. Standard conversion: Date The tag <f:convertDateTime> ensures the conversion Date String. By default, a date is posted in a following way: "Sat Jul 22 12:56: 12 CEST 2006" what corresponds to Saturday July 22, 2006. The tag <f:convertDateTime> has the following attributes: Table 1. Attribute Type Description Defines the date format. The values are: default, short, medium, long et full For the date Saturday 22th july 2006 the different values are: default: " Sat Jul 22 13:05:30 CEST 2006 " dateStyle String short: " 22/07/06 " medium: " 22 juil. 2006 " long: " 22 juillet 2006 " full: " samedi 22 juillet 2006 " timeStyle String locale timeZone pattern type Defines the time format. The values are: default, short, medium, long and full
String or The local for representing the date Locale String or Defines the time zone for which one represents the date. TimeZone String String Allows defining a personalized date format. It is necessary to use a pattern which is defined in the documentation of the class "SimpleDateFormat"of J2SE. If this attribute is defined, it is used instead of dateStyle and timeStyle. Allows specifying if the value to be represented is a date, a time or both. The values are: date (by default), time and both.
Example:
<h:inputText value="#{bean.date}"> <f:convertDateTime dateStyle="full" /> </h: inputText >
Now let?s see an example of a form which makes it possible to seize a date in the format "dd/mmyy" and which then transforms the string in a Date object. For that it is necessary to use the attribute "pattern" and to define the date format to be used. In our case it is "dd/MMyy":
<h:form> <h:inputText id="date" value="#{bean.date}"> <h:outputLabel for="date" value="Date (dd/mm/yy): " /> <f:convertDateTime pattern="dd/MM/yy" /> </h:inputText> <h:commandButton value="valider" /> </h:form>
Standard conversion : Number The tag <f:convertNumber > ensures the conversion Number String. This tag has the following attributes : Table 2. Attribute currencyCode currencySymbol locale integerOnly Type String String String or Locale boolean Monetary symbol. The local to represent the number. If "true" only the whole part of the number will be considered. Maximum number of digits after the comma. Minimum number of digits after the comma. Maximum number of digits before the comma. Minimum number of digits before the comma. Defines what the number represents. The possible values are: Number (default value), currency, percentage. Description Code ISO4217 used for monetary conversions
maxFractionDigits int minFractionDigits int maxIntegerDigits int minIntegerDigits type int String
Page 78 of 100
17/10/09 18:17
Custom convertor If the base converters are not enough for you, it is possible to create your own. You only have to implement "javax.faces.convert.Converter". The 2 methods to be redefined are:
/** * @param value This string value is used to create/retrieve an object */ Object getAsObject(FacesContext context, UIComponent component, String value); /** * @param value This object is used to create/retrieve an object */ String getAsString(FacesContext context, UIComponent component, Object value);
The 2 methods have as parameter the FacesContext instance and the component for which one the conversion is done. Before being able to use this converter, it should be declared. That is made in the file "faces-config. xml" using the tag <converter>. Example:
<converter> <description>Mon premier convertisseur</description> <converter-id>myConv</converter-id> <converter-class>com.labosun.converter.MyConverter</converter-class> </converter>
The tag <description> makes it possible to give a description to the converter. The tag <converter-id> will define the identifier of the converter in JSF pages. Finally the tag <converter-class> represents the class of your converter. There are 2 manners of using a converter: thanks to the attribute " converter " thanks to the attribute <f:converter>. While passing by the attribute "converter", it is enough to refer the identifier of the converter. Example:
<h:outputText value="#{conv.person}" converter="myConv" />
With the tag <f:converter>, the attribute "converterId" must refer the identifier of the converter. Example:
<h:outputText value="#{conv.person}"> <f:converter converterId="myConv" /> </h:outputText>
Convertor for lists At the time of the chapter on Checkbox, Radio Buttons, lists and Combobox, we saw that it was necessary to use a converter to store personalized objects. For recall, the tags concerned are: selectManyCheckbox selectOneRadio selectOneListBox, selectManyListBox selectOneMenu In this example, we will use the tag selectOneRadio which will make it possible to choose between several instances of the following class "Persson":
public class Person { public static int IDS = 0; private int id; private String lastName; private String firstName; public Person(int id, String firstName, String lastName) { this.id = id; this.lastName = lastName; this.firstName = firstName; } //Getters et setters for all the properties ... public String toString() { if (firstName.length() > 1) { return this.firstName + " " + this.lastName; } else { return this.lastName; } } }
This class simply defines a person who has a unique identifier, a name and a first name.. We will now define the bean which will define the list of SelectItem. We will start by seeing what happens without data converter.
package com.labosun; public class PersonConv { /**
Page 79 of 100
17/10/09 18:17
* This list simulat at data source */ public static final List<Person> PERSONS_LIST = new ArrayList<Person>(); static { PERSONS_LIST.add(new Person(1, "Jo", "Johnson")); PERSONS_LIST.add(new Person(2, "Raymond", "Schmitt")); PERSONS_LIST.add(new Person(3, "Bob", "LeNain")); } /** * SelectItem list which return the content of a select request .... */ private List<SelectItem> allPersons; /** * A person currently selected */ private Person person; public PersonConv() { allPersons = new ArrayList<SelectItem>(); for (int i = 0; i < PERSONS_LIST.size() 1;i++) { Person p = PERSONS_LIST.get(i); this.allPersons.add(new SelectItem(p, p.toString())); } Person p = new Person(3, "Bob", "LeNain"); this.allPersons.add(new SelectItem(p, p.toString())); } //Getters et setters for all the properties ... }
The constructor creates a list of SelectItem (Al) from our list of people (PERSON_LIST). But the last instance of people is not taken out of the list, this is voluntary, you will understand later why. Here now our JSF page. It contains as many radio buttons as there are people in the list and it posts the currently selected element?
<h:form> <h:selectOneRadio id="persRadio1" value="#{personList.person}"> <f:selectItems value="#{personList.allPersons}" /> </h:selectOneRadio> <h:message for="persRadio1" /> <br /> Rsultat: <h:outputText value="#{personList.person}" /> <br /><br /> <h:commandButton value="Valider" /> </h:form>
The result :
If you try to validate, the following error occurs:
Notice: error message should be displayed in English if your web browser is configurer in English. Indeed, JSF is completely internationalized in almost 10 languages (including Chineese). Take a look at the following HTML code :
Jo Johnson <input type="radio" value="Jo Johnson" /> Raymond Schmitt <input type="radio" value="Raymond Schmitt" /> Bob LeNain <input type="radio" value="Bob LeNain" />
We can see here that the value of the radio buttons (attribute value in HTML code) uses the method toString () of the class Persson. That means if JSF page is translated into HTML, the objects of type Person are translated into a String thanks to the method toString (). But when the tree of JSF components must be rebuilt, the JSF Servlet does not know how to reinstantiate the object Persson from this String. Therefor it is necessary to create a converter which will take care of this translation. To create the converter, we are using the "Person" identifier.
package com.labosun; public class PersonConv implements Converter { ... /** * @param value person " id ". * @return an object related to the id */ public Object getAsObject(FacesContext ctx, UIComponent component, String value) { int id = Integer.valueOf(value); for (Person p : PERSONS_LIST) { if (p.getId() == id) { return p; } } return null; } /** * @param value A " person " object.
Page 80 of 100
17/10/09 18:17
* @return " id " of the person. */ public String getAsString(FacesContext ctx, UIComponent component, Object value) { if (value == null || !(value instanceof Person)) { return ""; } return "" + ((Person) value).getId(); } }
The converter has to be declared:

<converter> <converter-id>persConv</converter-id> <converter-class>com.labosun.PersonConv</converter-class> </converter>
It now remains to refer the converter in our tag selectOneRadio:

<h:selectOneRadio id="persRadio1" value="#{personList.person}" converter="persConv"> <f:selectItems value="#{personList.allPersons}" /> </h:selectOneRadio>
Everythings works very well for the first 2 instances, but when the 3rd button is selected, the following error occurs:
If you have a look at the HTML code, we can see:

Jo Johnson <input type="radio" value="1" /> Raymond Schmitt <input type="radio" value="2" /> Bob LeNain<input type="radio" value="3" />
The radio button value use identifiers related to the objects. The error message specific to the 3rd button occurs because JSF will check if the object returned by the converter belongs well to the list of the items. This checking is done using the methods hashCode () and equals (). In our case, our converter returns instances coming from object "PERSONS_LIST", and then JSF will check if the returned instances belong tothe list "allPersons". But, remember that only the first 2 instances of the list "allPersons" come from list "PERSONS_LIST". As the class Persson does not redefine the methods hashCode () and equals (), it is those of the class Object which are used. This means that the equality is only based on the equality of the references (==). So this only works for the 2 first instances. So that this works for all the cases, it is enough to implement these 2 methods in the class Person:
public boolean equals(Object o) { if (o == null || getClass() != o.getClass()) { return false; } return this.getId() == ((Person) o).getId(); } public int hashCode() { return this.getId(); }
Now everything works fine. In short it is necessary: Create a converter (Implement Converter). Define the converter in "faces-config.xml" Reference the converter in the tag select.... (attribute converter) Implement the methods hashCode() and equals() This example is simply adaptable to a tag of type selectMany...
Validation
JSF makes it possible to validate all the data seized by the user. The validation is only possible for the components which implement EditableValueHolder. I.e. the text fields, the checkboxes, the radio buttons, the lists and the comboboxes.
The validation is carried out during the phase "Validation of the user entries". Attention, during this one, all the elements are not yet up to date (the javabeans are updated only during the "Update model" phase). If there are several validations, the order of treatments of the validations is the order of the tag declarations. Note: If the component which declares the validation has the attribute "immediate" set to true, then the validation is treated during the phase "Request parameters application". That makes it possible to force a validation to be done before all the others. For example, a person wishes to be recorded on a site. It must seize the country and the city in which it lives. The validation of the country can be made immediately to be sure that the validation of the city is considering the country. To force the user to seize a value, you can set the attribute "required" to true. Example:
Page 81 of 100
17/10/09 18:17
<h:inputText required="true" />
To carry out a more precise control on the data, a validator should be used. JSF provides 3 standard validateurs. They are usable thanks to the tags: <f:validateDoubleRange>, allows to test if a number with comma is in a range. <f:validateLength>, allows to test the length of a string. <f:validateLongRange>, allows to test if an integer is in a range. All these tags have the attributes "minimum" and "maximum" which define the ranges in which a value must be to be valid. Example :
<h:form> ... <h:inputText id="name"> <h:outputLabel for="name" value="Name:" /> <f:validateLength minimum="3" maximum="10" /> </h:inputText> <%-- Display a validation message --%> <h:message for="name" /> ... </h:form>
Here the entire form will not be validated if the value entered for this field text does not have a length ranging between 3 and 10. The validation errors are posted by the tag <h:message>. Custom validator It is possible to create its own validator. There are 2 manners of making it, either by using a method, either by implementing the interface " javax.faces.validator.Validator ".
Generic method
Any JavaBean can declare the method, but it must be referred as JavaBean is managed by the container. The method which manages the validation must have the following prototype:
public void validate(javax.faces.context.FacesContext context, javax.faces.component.UIComponent component, Object value) { //Event handling }
If there is a validation error, the method must throw a "javax.faces.Validator.ValidatorException". The constructor takes as parameter an object of type "javax.faces.application.FacesMessage", i.e. a message which is intended for the user. This message will then be posted thanks to the tag <h:message>. The method can then be referred thanks to the attribute " validator ".
<h:inputText validator="#{nomDuBean.methodName }" />
Interface
It is necessary to implement the interface javax.faces.validator.Validator . The only method to redefine :

public void validate(FacesContext context, UIComponent component, Object value);
To use this validator, it should be declared in the file "faces-config. xml" using the tag <validator>. Example :
<validator>  <validator-id>emailValidator</validator-id>  <validator-class>com.labosun.validation.EmailValidator</validator-class> </validator>
The validator can then be used thanks to the tag <f:validator>, the attribute "validatorId" must refer the identifier of the validator. Example :
<h:inputText> <f:validator validatorId="emailValidator" /> </h:inputText>
Example: Email validator To illustrate the operation of a validation, we will create a very basic email validator. We will just check the presence of the character @ .
public void validate(FacesContext context, UIComponent component, Object value) throws ValidatorException { if ((context == null) || (component == null)) { throw new NullPointerException(); } if (value != null) { String field = (String) value; if (field.contains("@") == false) { FacesMessage fm = new FacesMessage("Email is not compliant"); throw new ValidatorException(fm); } } }
We are now declaring our bean in the file faces-config.xml .
Page 82 of 100
17/10/09 18:17
<managed-bean> <managed-bean-name>beanMail</managed-bean-name> <managed-beanclass>com.labosun.EmailValidator</managed-bean-class> <managed-bean-scope>application</managed-bean-scope> </managed-bean>
The last thing to do is to write the code of the page and to refer the method of our bean by using the attribute Validator.
<h:form> <h:inputText id="emailMethod" validator="#{beanMail.checkEmail}"> <h:outputLabel for="emailMethod" value="Email:" /> </h:inputText> <h:message for="emailMethod" /> <br /> <h:commandButton value="Vrifier l'email" /> </h:form>
If a text which was entered does not contain an "@", the tag <h:message> posts the message "an email must contain an @"..
Advanced concept
Internationalization
The internationalization of JSF pages is done with properties file. A properties file is a list of keys / values. See the tutorial of Sun for more informations on properties file here : http://java.sun.com/docs/books/tutorial/i18n/index.html. To use a properties file in a JSF page, the <f:loadBundle> tag is used like this :
<f:loadBundle basename="fileName" var="variable" />
The attribute basename indicate the name of the properties file who will be used. Caution, if the file is in a package, you will need to prefix the file by the package name. The attribute var will be used in the page to reach the ressources file. We reach one key defined in the ressources file like this :
<h:outputText value="#{variable.keyName}" />
Example: We have a properties file called SiteMessages.properties in the com.labosun package. This properties file contains this line :
message=hello
To use it in a page, this code will be used :

<f:loadBundle basename="com.labosun.SiteMessages" var="msg"/> <f:view> <h:outputText value="#{msg.message}"/> </f:view>
In this case, the locale used will be the locale of the users. If you want to change the default locale, you need to use this code in the file faces-config.xml :
<application> <localeconfig> <defaultlocale>en</defaultlocale> </localeconfig> </application>
The chapter 8.1.3 Example: Change language button explain how change the locale. Dynamic internationalization It is sometimes need to reach a properties file from a JavaBean. To do this, it is necessary to use the getBundle method from the RessourceBundle method. The first attribute of this method is the name of the properties file, and the second is the locale we want to use.
FacesContext context = FacesContext.getCurrentInstance(); String basename = "conf.SiteMessages"; String key = "dynamicMessage"; String message; try { ResourceBundle bundle = ResourceBundle.getBundle(basename, context.getViewRoot().getLocale()); } catch (Exception e) { // exception handling } // retrieving a localized message message = bundle.getString(key);
Encoding Normalement la notion d?encodage a dj t vue dans le cours JSP, mais pour rappel, il est possible de changer l? encodage des pages grce la directive de page : The encoding concept has already been seen, but for recall, it is possible to change the encoding of apages with the following attributes:
<%@ page pageEncoding="UTF8" contentType="text/html; charset=UTF8" %>
By default it is the value ISO-8859-1 which is used. The list of available encoding is on the page: http://java.sun.com/j2se/1.4.2/docs/guide/intl/encoding.doc.html Example: Change language button
Page 83 of 100
17/10/09 18:17
In this example, we will sight how changed the site language, when an user click on a link. Starting with make the Web page. The current locale will be shown and 4 link will perform the language change.
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> <%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %> <html> <body> <f:view> <%-- We load the properties file --%> <f:loadBundle basename="com.labosun.i18n.ChangeLocaleRB" var="change" /> <%-- Print the current locale --%> <h:outputText value="#{change.currentLocale} #{changeBean.changeLocale}" /> <br /> <h:form> <%-- Link to change language --%> <h:commandLink id="FR" value="#{change.french}" actionListener="#{changeBean.changeLocale}" /><br /> <h:commandLink id="US" value="#{change.english}" actionListener="#{changeBean.changeLocale}" /><br /> <h:commandLink id="CA" value="#{change.canadian}" actionListener="#{changeBean.changeLocale}" /><br /> <h:commandLink id="DE" value="#{change.deutsch}" actionListener="#{changeBean.changeLocale}" /><br /> </h:form> </f:view> </body> </html>
This page use properties files. Here is the contents of 2 properties files ( english and french ) : File ChangeLocaleRB_fr.properties :
currentLocale=La Locale actuelle est french=Franais english=Anglais canadian=Canadien deutsch=Allemand
File ChangeLocaleRB_en.properties :
currentLocale=The current Locale is french=French english=English canadian=Canadian deutsch=Deutsch
We need now to write the JavaBean who will perform the language change :
package com.labosun.i18n; import javax.faces.component.UIComponent; import javax.faces.context.FacesContext; import javax.faces.event.ActionEvent; import java.util.Locale; public class ChangeBean { /** * Contains the current locale */ private Locale currentLocale = FacesContext.getCurrentInstance(). getViewRoot().getLocale(); public Locale getCurrentLocale() { return currentLocale; } /** * Change the locale of the current view. * @param newLocale La nouvelle Locale */ public void setCurrentLocale(Locale newLocale) { FacesContext.getCurrentInstance().getViewRoot().setLocale(newLocale); this.currentLocale = newLocale; } public void changeLocale(ActionEvent ae) { String id = ae.getComponent().getId(); Locale newLocale = null; // we get all available locale Locale[] locales = Locale.getAvailableLocales(); for (int i = 0; newLocale == null && i < locales.length; i++) { if(locales[i].getCountry().equals(id)) { newLocale = locales[i]; } } if (newLocale == null) { newLocale = Locale.getDefault(); } setCurrentLocale(newLocale); } }
Then we must declare this Javabean in the file: faces-config. xml :

<faces-config> <managed-bean> <managed-bean-name>changeBean</managed-bean-name> <managed-bean-class>com.labosun.i18n.ChangeBean</managed-bean-class> <managed-bean-scope>application</managed-bean-scope> </managed-bean> </faces-config>
Messages management
As seen at the chapter 5.15 Error message , all errors are moved up to the user via a message system. Here, it is
Page 84 of 100

possible since any type of JavaBean (actionListener, converter, validation, ...) to send a message who will be printed in a page. A JSF message is represent by the javax.faces.application.FacesMessage class. Each message have a summray of the error ( properties summary ), a detail of the error ( properties detail ), and the severity of the error ( properties severity ). Messages are saved in the application with the addMessage(String clientId, FacesMessage message) method of the FacesContext class. The attribute cliendId allows to link the message to acomponent, if its null, then it is a global message. To have a valid identifier, the easiest way is to get directly the component identifier with the UIComponent.getId() method. Let us see now an example of making messages from a Javabean:
17/10/09 18:17
package com.labosun.message; import javax.faces.application.FacesMessage; import javax.faces.component.UIInput; import javax.faces.context.FacesContext; import javax.faces.event.ActionEvent; public class MessageBean { private UIInput nameInput; public UIInput getNameInput() { return nameInput; } public void setNameInput(UIInput nameInput) { this.nameInput = nameInput; } public void check(ActionEvent ae) { FacesContext context = FacesContext.getCurrentInstance(); //Retrieve component id String nameId = nameInput.getClientId(context); FacesMessage f = new FacesMessage(FacesMessage.SEVERITY_WARN, "Global message summary", "message from MessageBean"); context.addMessage(null, f); FacesMessage f2 = new FacesMessage(FacesMessage.SEVERITY_INFO, "Specific message summmary", "message from MessageBean and specif context.addMessage(nameId, f2); } }
The attribute nameInput will be linked with a component for recovered its identifier. The check method is used as ActionListenener. It is it which make the two messages f and f2 . The first message is global since one does not use an identifier at the context addition. The second message is specific to the component nameInput . To link the attribute nameInput with the component of text type in the JSF page, we need to use the attribute binding .
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> <%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %> <html> <head> <link href="style.css" rel="stylesheet" type="text/css" /> </head> <body> <f:view> <h:messages globalOnly="true" showDetail="false" showSummary="true" styleClass="errorTable" errorClass="error" infoClass="info" fatalClass="fatal" warnClass="warn" /> <h:form> <h:inputText id="name" size="10" binding="#{messageBean.nameInput}"> <h:outputLabel for="name" value="Name:" /> </h:inputText> <h:message for="name" styleClass="errorTable" errorClass="error" infoClass="info" fatalClass="fatal" warnClass="warn" /> <h:commandButton value="Valider" actionListener="#{messageBean.check}"/> <br /> <h3>List</h3> <h:messages showDetail="true" showSummary="true" styleClass="errorTable" errorClass="error" infoClass="info" fatalClass="fatal" warnClass="warn" /> <h3>Table</h3> <h:messages showDetail="true" showSummary="false" layout="table" styleClass="errorTable" errorClass="error" infoClass="info" fatalClass="fatal" warnClass="warn" /> </h:form> </f:view> </body> </html>
Last stage, we need to save the JavaBean in the faces-config.xml file.

<managed-bean> <managed-bean-name>messageBean</managed-bean-name> <managed-bean-class>com.labosun.message.MessageBean</managed-bean-class> <managed-bean-scope>request</managed-bean-scope> </managed-bean>
Customize messages The default errors messages not always correspond to your application. Fortunately it is possible to change these. In JSF 1.2, all components who inherit of UIInput allows personalization of the message very easily with 3 attributes : converterMessage : define the message when the value of the component can't be convert. requiredMessage : define the message when no value is entered. validatorMessage : define the message used when the entered value is not validated by the component. For all others messages and for JSF 1.1, the default errors messages are in the Message_fr.properties properties file, who is in the java.faces package, of jsfimpl.jar jar file. It is impossible to redefine these messages by creating a new properties file with the same keys. This new file can be anywhere in your application. We will then define it to replace the default file. For example, we will create the MyDefaultMessages_fr.properties file, in which, we will copy the keys/values of the original Message_fr.properties file.
javax.faces.component.UIInput.REQUIRED= Validation error : You must enter a value.
Page 85 of 100
17/10/09 18:17
javax.faces.validator.LengthValidator.MAXIMUM= Validation error : the value is superior to the maximum authorized : , ''{0}''
You will notice that all special characters are unicode. In these messages, syntax "{0}" allows insert of parameters. This uses the MessageFormat class. Now, we will put these messages:
javax.faces.component.UIInput.REQUIRED= Personalized message : This field is required. javax.faces.validator.LengthValidator.MAXIMUM= Personalized message : The value ''{0}'' is superior to the maximum authorized for this field.
This file is used in place of the default file. It is defined in the JSF configuration file:
<faces-config> <application> <locale-config> <default-locale>fr</default-locale> </locale-config> <message-bundle>MyDefaultMessages</message-bundle> </application> </faces-config>
JSF Integration in JEE application

The new JEE 5 specification bring annotation who can be used for interact with the lower layer of your application, with the injection principle. For this, we will define a variable who will be create by the container. We need a JEE 5 valid server to use these annotations. Resource injection Ressources injection allow by example to get an instance of the JNDI current context. It is used with the annotation @Ressource . Example :
@Resource private SessionContext ctx;
With the deployment of application, the variable of "ctx" will be initialized. EJB injection EJB injection allows getting an instance of Local or Remote interface. It is used with the annotation @EJB . Example :
@EJB private Store store;
Is is also possible to use ressources injection to get an instance on JNDI current context and to seek then the EJB. Example:
@Resource private SessionContext ctx; Store store = (Store)ctx.lookup("Store");
WebService injection It is possible to get a WebServices who inherit of javax.xml.ws.Service . Injection is used with the annotation @WebServiceRef .
@WebServiceRef public StockQuoteService stockQuoteService;
Persistence unit injection It is possible to get an instance of one EntityManager. Like in EJB3, injection is done with the annotation @PersistanceContext . The unitName field allows informing the unit of persistence name to be used. To be valid, this field must be defined in the persistence.xml file. Example:
@PersistenceContext(unitName="InventoryManagement") EntityManager em;
Facelets
Introduction
JSF was designed to work with JSP, but it is obvious there are numerous problems when both are mixed. To only quote one, the unified language EL should be used in two different ways according to the JSP or JSF context (syntax ${} and #{}). The Facelets goal is to create a set of tags that are well matched with JSF and also give a new way to write JSF code. It does not add new internal mechanisms to JSF, but settles to easy the writing of code by letting code template creation. Facelets works with the JSF implementations 1.1 and 1.2 of Sun and Apache MyFaces. Facelets also provides the following enhancements: Possibility to create pages in several files More precise display of errors Quicker creation of custom tags
Page 86 of 100

Simple configuration Let to use JSF tags as standard HTML ones (attribute jsfc, see the chapter "JSFC") To understand what brings Facelets, we have to come back to the life cycle of a Web page. JSF was designed to be modular, this means it is possible to change some components in the JSF internal. Facelets deals with replacing view components, ie. the phases "View Restoration" et "Reply Rendering". Other phases stay unchanged. Here is a reminder of the life cycle. Yellow parts are managed by Facelets:
17/10/09 18:17
Thanks to the control of those two phases, all the syntax of the files can be changed and entirely retought by Facelets.
Configuration
In this chapter, we will see how to install and configure Facelets to use it in a project. Installation First of all, you should download the last implementation of Facelets at this address: https://facelets.dev.java.net/ This lesson is based on version "1.1.11". You then have to uncompress the archive and get the file "jsf-facelets.jar". In the case where you do not use a JEE 5 server, you should take the files "el-api.jar" and "el-ri.jar" that are placed in the directory "lib". Project Structure Facelets respects the same structure as a standard JSF application. The only difference is the extension of Web pages, it is ".xhtml". This extension is not mandatory, but the syntax of Facelets follow the xHTML format. It is then more logical to use that extension. The structure of a War file stays the same as for JSF. Here it is: Table 1. WEB-INF/classes WEB-INF/lib WEB-INF/facesconfig.xml WEB-INF/web.xml *.xhtml All ".xhtml" files should be placed at the root. Those are Facelets pages. Contains all the Java classes (the JavaBeans, among others). Every libraries (jar) needed by the project. The Facelet library: "jsf-facelets.jar". Eventually: "elapi.jar" and "el-ri.jar". Configuration file.
Configuration We are now going to see modifications to do to the files "faces-config.xml" and "web.xml" pour to be able to use Facelets. First of all, we will define the extension ".xhtml" as pages extension. As seen in the chapter "Context parameters ", we shall use the context parameter "javax.faces.DEFAULT_SUFFIX".
<web-app>  <context-param> <param-name>javax.faces.DEFAULT_SUFFIX</param-name> <param-value>.xhtml</param-value> </context-param>  <context-param> <param-name>facelets.DEVELOPMENT</param-name> <param-value>true</param-value> </context-param> </web-app>
Page 87 of 100
17/10/09 18:17
In the following examples, the suffit ".jsf" is used. This allows to call a page by replacing the extension ".xhtml" by ".jsf". To remind you, here is how to declare it:
<web-app> <servlet> <servlet-name>Faces Servlet</servlet-name> <servlet-class>javax.faces.webapp.FacesServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>Faces Servlet</servlet-name> <url-pattern>*.jsf</url-pattern> </servlet-mapping> </webapp>
We now need the JSF Servlet forward calls to Facelets for the view management. This is done in the file "facesconfig.xml":
<faces-config> <application> <view-handler> com.sun.facelets.FaceletViewHandler</view-handler> </application> </faces-config>
Thanks to this configuration, the view management (creation of the JSF component tree, rendering of the reply) will be managed by Facelets and not by the JSF implementation anymore.
Core Concepts
Page Structure The structure of the facelet pages respect the format xHTML. Here is a first example of a Facelets page: Hello.xhtml :
<?xml version="1.0" encoding="UTF8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core"> <body> <h:outputText value="Hello" /> #{param.f} </body> </html>
The first different in relation to a classical JSF page is that the taglibs declaration is different. Here, we declare all the libraries like namespaces in the <html> tag. The expression "xmlns:ui=http://java.sun.com/jsf/facelets" allows to use all the Facelets tags. Whereas the two next ones allow to use the JSF libraries. There is no tag <f:view>. Finally, it is possible to use an EL expression directly in the HTML code. For instance, the code "#{param.f}" displays directly the value of the parameter "f". If we execure this page by setting the parameter "f=Facelets" in the URL, we get the text:
Hello Facelets
This is an example assuming "JSFCoursFacelets" if the context of the project and "Hello.jsf" is the name of the page. We must use the URL: http://localhost:8080/JSFCoursFacelets/Hello.jsf?f=Facelets . JSFC One of the problems that arise with the JSF tags is that editors do not all know how to render a page in a graphics way. However, most of code editors know how to display an HTML page. One of the possibilities offered by Facelets is to display the result of a page as HTML and without it being executed on the server. This is done thanks to the attribute "jsfc". Let us see an example:
<?xml version="1.0" encoding="UTF8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF8"/> <title>Form with JSFC</title> </head> <body> <form jsfc="h:form"> <input id="name" type="text" jsfc="h:inputText" value="#{bean.name}" required="true"> <label for="name">Name:</label> </input> <h:message for="name" /> <br /> <button type="submit" jsfc="h:commandButton" value="Validate" /> </form> </body> </html>
Let us take the tag <form jsfc="h:form">, Facelets will do the interpretation as a tag <h:form>, but from a code editor perspective it is only a simple <form> tag. The attribute "jsfc" serves to define the real type of the tag. The advantage
Page 88 of 100

here is to be able to work with standard HTML tags and let let editors graphically display them in a simple editor. Attributes specifics to a JSF tag should be added to the HTML tag. An HTML editor will certainly indicate that the attribute does not exist for that tag, but it will work correctly for Facelets. This is the case for the attribute "required" for the tag <input>. For the JSF tags that do not have HTML equivalents like the tag <h:message> for instance, we should include it directly in the code. We then get a mix of HTML and JSF tags, without forgetting that we always still can add EL expressions directly in the HTML code. Template A template is a Facelets code that can be reused. Templates will be applied at wish in the site. this is the equivalent of a tag, except that a template is written in a very simple manner and is more easily modular. A page that uses a template is named a "calling page". We will later see that there are several manners to use a template. This lesson part is only concentrating on the basic declaration of a template. Every Facelets file can serve as a template. By default, this is all of a page that defines a template. Template1.xhtml:
<?xml version="1.0" encoding="UTF8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF8"/> <title></title> </head> <body> </body> </html>
17/10/09 18:17
Here, the entire page is considered as a template. To only use a portion of code as a template, we must use the tag <ui:composition>. Template2.xhtml:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF8"/> <title></title> </head> <body> <ui:composition template="Template1.xhtml"> </ui:composition> </body> </html>
The result of this example will be that the content of the page "template1.xhtml" will be displayed on the client. This example is quite limited because it is equivalent to the inclusion of a page. We will see in the next chapter how to create and use modifiable templates. In this example, all the tags of the pages that use the template are ignored. This behavior is specific to the tag <ui:composition>, the chapter "Facelets" will present other tags to use templates.
View Templating
Now that we understand the basic syntax of Facelets and the concept of templates, we will see how this can be done in practice. One of the most occurring problems during the creation of a Web site is that every page should redefine all the page layout of the site. Ie. redefine the title, the menu, the footer... Those elements are often the sames for every pages of the site. It is more practical to only declare them once and that they get integrated directly to other pages. Facelets allow to do that thanks to its template system. Let us see how it works with a first example First of all, we must write the template page. it will describe the structure of the site and the elements that other pages can modify. In our example, we will create a site that contains a header, a menu, a body and a footer. MainTemplate.xhtml:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF8"/> <title> <ui:insert name="Title">Default Title</ui:insert> </title> </head> <body> <div style="background: cornflowerblue; position: absolute; left: 0%; right:0%; bottom: 95%; top: 0%"> <ui:insert name="Header"> <ui:include src="Header.xhtml" /> </ui:insert> </div>
Page 89 of 100
17/10/09 18:17
<div style="background: darksalmon; position: absolute; left: 0%; right: 90%; bottom: 5%; top: 5%;"> <ui:insert name="Menu"> <a href="">Default Menu 1</a><br /> <a href="">Default Menu 2</a><br /> <a href="">Default Menu 3</a><br /> </ui:insert> </div> <div style="position: absolute; left: 10%; right: 0%; bottom: 5%; top: 5%;"> <ui:insert name="Body"> Default Body </ui:insert> </div> <div style="background: lawngreen; position: absolute; left: 0%; right: 0%;bottom: 0%; top: 95%"> <ui:insert name="Footer"> Default Footer </ui:insert> </div> </body> </html>
There are two tags specific to Facelets in this template page, <ui:insert> and <ui:include>. First, the tags <ui:insert> allow to define the modifiable parts of the template. Each tag use a name to uniquely identify the part In the case of the tag:
<ui:insert name="Footer"> Default Footer </ui:insert>
It defines all the footer part that is modifiable. The text "Default Footer" is the text displayed by default, when another page that use the template to not modify the footer. For the tag:
<ui:insert name="Header"> <ui:include src="Header.xhtml" /> </ui:insert>
It does not define directly the default header, but import a file that contains the default text. The import is done with the tag <ui:include>. HeaderTemplate.xhtml:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF8"/> <title></title> </head> <body> <ui:composition> Default Header </ui:composition> </body> </html>
This page contains the default code for the header. The tag <ui:composition> is used to define a bloc of code that can be reused in other pages. In fact, all the code that is arround the tag <ui:composition> is ignored, that means that it will never appear in an HTML page received by the client. This behavior is due to the tag <ui:include> that ignores the rest of the page as soon as it finds a tag <ui:composition>. We will see the inclusion principle in detail in the chapter " 1.4.5 Include ". Our template is now read, we can create the page that will use the template. PageMain.xhtml:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF8"/> <title>Main Page</title> </head> <body> <ui:composition template="MainTemplate.xhtml">  <ui:define name="Title">Main Page</ui:define> <ui:define name="Footer">Footer</ui:define> <ui:define name="Body">Redefined body of the page</ui:define> </ui:composition> </body> </html>
The tag " <ui:composition>":

<ui:composition template="MainTemplate.xhtml"> ... </ui:composition>
It uses the attribute "template". In this case, it does not serve to declare a template (like in HeaderTemplate.xhtml) but to precise that we want to use an existing bloc of code. In our case, we begin by taking all the code of the page of the attribute "template", "MainTemplate.xhtml". Then, we replace the modifiable parts (bodies of the tags <ui:insert>) by the content of the tags <ui:define>. Here, we do not modify the parts "Title", "Footer" and "Body". The order of the tags "define" does not matter. It is not mandatory to
Page 90 of 100

redefine all parts. If "JSFCoursFacelets" is the context of the project, this page is available at the address: http://localhost:18080/JSFCoursFacelets/PageMain.jsf The graphical result is:
17/10/09 18:17
Be Careful: In the last page "PageMain.xhtml", every tags <ui:define> that is outside of the dirst <ui:composition> tag are ignored. Moreover, all the code that is not inside valid <ui:define> tags are also ignored. Ie. the following code will generate the same HTML page. All grayed parts are not included in the HTML page that the client receives.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF8"/> <title>Main Page</title> </head> <body>  <ui:define name="Title">Title not took into account</ui:define>  <ui:composition template="MainTemplate.xhtml">  <ui:define name="Title">Main Page</ui:define> This text is ignored  <ui:define name="Footer">Footer</ui:define>  <ui:define name="Body">Redefined body of the main page</ui:define> </ui:composition>  <ui:define name="Menu">Menu not took into account</ui:define>  <ui:composition template="MainTemplate.xhtml"> <ui:define name="Menu">Menu</ui:define> <ui:define name="Body">The body, again.</ui:define> </ui:composition> </body> </html>
The working of the different tas will be reviewed in detail in the rest of the lesson. It is possible, from this exemple, to create a skeleton of page that you can reuse as you wish.
Facelets Tags
Composition The tag <ui:composition> allows: Either to define a template zone, Or to use a template by eventually adding modifications (using the attribute "template").
Define a Template
Take the first case to define a template zone. Example:

<ui:composition> Reusable part. </ui:composition>
It is possible to use <ui:insert> tags to define what zones of the template are modifiables.
Page 91 of 100

Template Usage
17/10/09 18:17
A template can be used with the tag <ui:composition>. In this case, the attribute "template" must define the URL to the files of the template to use. The usage of a template follow those rules: If the template file contains one or several <composition> tags then only the body of the first tag is took into account, Else, all the page is took into account. In every cases, the code that is arround the tag <composition> in a calling page is not included in the final reply. See the chapter " 1.3 View Templating " for an example of use where only the calling page use the tag <ui:composition>. We will see here a second example where the template page and the calling page both use the tag <ui:composition>.
Example
TemplateWithComposition.xhtml:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF8"/> <title></title> </head> <body> <ui:composition> <div style="..."> <ui:insert name="Header">Header</ui:insert> </div> <div style="..."> <ui:insert name="Body">Default body.</ui:insert> </div> </ui:composition> </body> </html>
UseTemplateWithComposition.xhtml:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF8"/> <title></title> </head> <body> <ui:composition template="TemplateWithComposition.xhtml"> <ui:define name="Header">header</ui:define> <ui:define name="Body">Redefined body of the main page.</ui:define> </ui:composition> </body> </html>
The result will be:

<div style="..."> Header </div> <div style="..."> Redefined body of the main page. </div>
Here, we see well that everything that is around the tags <ui:composition> is ignored.
Insert
The tag <ui:insert> can be used in templates. It defines a portion of code that can be replaced. The attribute "name" let you identify that portion. The replacing is then done by the tag <ui:define> that have an attribute "name" too. There only need to match both to do a replacement. Example:
<ui:insert name="Partie1"> Modifiable part. </ui:insert>
It is also possible to use the tag without specifying a name. In this case, all the body of the tags that uses the template will be included. Example without name: ParagraphTemplate.xhtml:
Start of paragraph <ui:insert /> End of paragraph
Page.xhtml:
<ui:composition template="Paragraph.xhtml"> Middle of paragraph </ui:composition>
Page 92 of 100

The generated page will be:
Start of paragraph Middle of paragraph End of paragraph
Define
17/10/09 18:17
The tag <ui:define> allow to replace the content of a tag <ui:insert>. It has the mandatory attribute "name" that must match a name of a <ui:insert> tag.
Decoration
The tag <ui:decoration> allow to use a template. It works like the tag <ui:composition> except that all the code of the calling page is included in the reply. We have the same page of template as in the chapter "Example". TemplateWithComposition.xhtml:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF8"/> <title></title> </head> <body> <ui:composition> <div style="..."> <ui:insert name="Header">Header</ui:insert> </div> <div style="..."> <ui:insert name="Body">Default body</ui:insert> </div> </ui:composition> </body> </html>
UseTemplateWithDecoration.xhtml:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF8"/> <title>Page principale</title> </head> <body> <ui:decorate template="TemplateWithComposition.xhtml"> <ui:define name="Header">Header</ui:define> <ui:define name="Body">Redefined body of the main page</ui:define> </ui:decorate> </body> </html>
The result will be:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF8"/> <title>Page principale</title> </head> <body> <div style="..."> Header </div> <div style="..."> Redefined body of the main page </div> </body> </html>
Include
The tag <ui:include> allow to include a Facelet page. It have the mandatory attribute "src" that designate the page to include. The name of the page can be wrote directly ou it can be an EL expression. Example that allow to include the page "Footer.xhtml":
<ui:include src="Footer.xhtml" />
The inclusion follows those rules: If the file to include contains one or several tags <composition> then only the content of the first tag is took into account. Else, all the page is took into account. This mechanism is interesting because one page can still define the tag <html> with all the namespaces, that allow to edit it in an editor.
Page 93 of 100

Param
17/10/09 18:17
The tag <ui:param> allow to pass parameters to a Facelets bloc of code. It can be used inside the tags <ui:define> and <ui:include>. It has those two mandatory attributes: name value
Remove
The tag <ui:remove> allow to not take into account all the code that is in its body. This is like a comment on a whole bloc (like /* and */). But this solution has the advantage to not have to comment every single line of code. Example:
<body> <h:outputText value="affich" /> <ui:remove> <h:outputText value="Not displayed" /> <form> <%-- <h:outputText value="Not displayed again" /> --%>  <button type="submit" /> </form> </ui:remove> <h:outputText value="Displayed" /> </body>
Here, all the part inside <ui:remove> is not took into account.
Component
The tag <ui:component> is identical to <ui:composition>, except that all the body of the tag is included in a JSF component that we can use. To use it, we should use the attribute "bindings".
Fragment
The tag <ui:fragment> is identical to <ui:component> in its working, but, like the tag <ui:decorate>, the tags of the calling page will be included in the final reply.
JSTL and Fonctions Tags
Facelets proposes an implementation of JSTL Core taglibs and of functions.

JSTL Core
To use the tags JSTL Core, we should declare the following namespace: "xmlns:c="http://java.sun.com/jstl/core"" Table 2. <c:if> Attribute Mandatory test var Yes No Description Expression to evaluate. If the expression is true then the body of the tag is took into account, else it is ignored. An expression null is false. Variable that must contains the result of the test of the expression.
Example:
<c:if test="#{user.roles['admin']}"> </c:if>
Table 3. <c:forEach> Attribute items var begin end step Description An expression that points to the Collection, the Map ou the table to browse. Contains the current element that we are browsing. Index from which to begin the iteration. Index to which to end the iteration. The value to add to the index at every iteration. Point to an object that contains the following properties: boolean first boolean last varStatus int begin int end int index int step
Table 4. <c:set> Attribute Description
Page 94 of 100

var value The variable that will contains the value of the attribute "value". The expression wich will determinate the value of the variable. This expression will be reused at every time the variable will be used. Ie. there is no copy of this value in the variable designated by the attribute "var".
17/10/09 18:17
Functions
To use the functions, we should declare the following namespace: "xmlns:fn="http://java.sun.com/jsp/jstl/functions"".
Components Templating
Problem with JSF Despite the simplicity of JSF, there are numerous cases where we are obliged to repeat code that is looking pretty the same. This is the case for presentation code, as we have seen in the chapter " 1.3 View Templating ", but the problems can also arise for personal components. Facelets Solution Thanks to its template system, Facelets allow to create a tag that we will use as a component. This tag will generate all the code for different copies. The only thing that we will have to provide is the list of attributes that can be changed between several copies of the code. CaseComponent.xhtml:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core" xmlns:c="http://java.sun.com/jstl/core" xmlns:fn="http://java.sun.com/jsp/jstl/functions"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF8"/> <title></title> </head> <body>  <ui:composition> <h:column> <f:facet name="header"> <h:panelGroup>  <c:if test="#{!empty sortMethod}"> <h:commandLink action="#{bean[sortMethod]}"> <h:outputText value="#{columnName}" /> </h:commandLink> </c:if>  <c:if test="#{empty sortMethod}"> <h:outputText value="#{columnName}" /> </c:if> </h:panelGroup> </f:facet> <h:outputText value="#{caseValue}" /> </h:column> </ui:composition> </body> </html>
TagFile To use this component template with to a tag, we must add it in a declaration file. The file must have the extension ".taglib.xml". labo-sun.taglib.xml:
<?xml version="1.0"?> <!DOCTYPE facelet-taglib PUBLIC "-//Sun Microsystems, Inc.//DTD Facelet Taglib 1.0//EN" "facelet-taglib_1_0.dtd"> <facelet-taglib> <namespace>http://www.labo-sun.com/jsf</namespace> <tag> <tag-name>case</tag-name> <source>CaseComponent.xhtml</source> </tag> </facelettaglib>
This declaration will allow to use our template with a tag of this kind:
<case columnName="" sortMethod="" caseValue="" bean="" />
The attributes of the tag are determined from the variables that are used in the template page. For Facelets to load the file, we must add the following declaration in the file web.xml:
<context-param> <param-name>facelets.LIBRARIES</param-name> <param-value>/WEB-INF/facelets/tags/arcmind.taglib.xml</param-value> </context-param>
Declaration:
Page 95 of 100
17/10/09 18:17
<managed-bean> <managed-bean-name>beanTable</managed-bean-name> <managed-bean-class>com.labosun.facelets.BeanTable</managed-bean-class> <managed-bean-scope>request</managed-bean-scope> </managed-bean> public class BeanTable { private List<Person> persons; private static Comparator<Person> personLastNameComparator = new Comparator<Person>() { public int compare(Person o1, Person o2) { return o1.getLastName().compareTo(o2.getLastName()); } }; private static Comparator<Person> personFirstNameComparator = new Comparator<Person>() { public int compare(Person o1, Person o2) { return o1.getFirstName().compareTo(o2.getFirstName()); } }; public BeanTable() { persons = new ArrayList<Person>(); persons.add(new Person("Bob", "Gnoliac")); persons.add(new Person("Thomas", "Anderson")); persons.add(new Person("Raymond", "Smith")); } //Getter et setter public void sortByFirstName() { Collections.sort(getPersons(), personFirstNameComparator); } public void sortByLastName() { Collections.sort(getPersons(), personLastNameComparator); } }
That's all, our tag is ready to be used. The declaration is done with namespaces like that:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core" xmlns:m="http://www.labo-sun.com/jsf"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF8"/> <title>Test column template</title> </head> <body> <h:form> <h:dataTable value="#{beanTable.persons}" var="person" border="1" rules="all"> <m:case columnName="Last name" sortMethod="sortByLastName" caseValue="#{person.lastName}" bean="#{beanTable}" /> <m:case columnName="First name" sortMethod="sortByFirstName" caseValue="#{person.firstName}" bean="#{beanTable}" /> </h:dataTable> </h:form> </body> </html>
Here is the final result: Table 5. Sort by Last Name Sort by First Name
Parameters
Table 6. Parameters Description List of paths to libraries of Facelets tags separated by ";". The paths are relative to the root of the applciation. A library is loaded only when the page that use it should be compiled. facelets.LIBRARIES Example: /WEB-INF/facelets/my.taglib.xml; /WEB-INF/facelets/car.taglib.xml; A list of classes (separated with ";" of the type "com.sun.facelets.tag.TagDecorator" with a default constructor. Those decorators will be loaded during the first query will get to the view "FaceletViewHandler". Example: com.sun.facelets.tag.jsf.html.HtmlDecorator facelets.DEVELOPMENT facelets.BUFFER_SIZE If true, then debugging informations will be displayed on the Web page when there is an error. The default value is false. The size of the buffer used by the ResponseWriter. Be careful, a too small buffer size will no allow to display a page in its entirety. By default, the value is 1, it allows to not
facelets.DECORATORS
Page 96 of 100

set any size limit. facelets.REFRESH_PERIOD Allow to define the minimum time interval that must wait the compilator before to check if a page should be recompiled (if there are any changes). The value 1 allow to prevent the compilator to check if there are changes once the page is compiled. The default value is 2. Allow to specify a custom ResourceResolver. The default value is: com.sun.facelets.impl.DefaultResourceResolver A list of URLs (separated by ";") that will be managed by Facelets. If nothing is precised, every requests will be managed by Facelets. In the case where an URL is not managed by Facelets, the parent default view (JSP) is used. Be careful, if you specify URLs, the mapping to the servler FacesServlet should be mapped for several types of files. Example: /faces/*;*.xhtml
17/10/09 18:17
facelets.RESOURCE_RESOLVER
facelets.VIEW_MAPPINGS
Bibliography
JSF tags documentation: JSF 1.1 : http://java.sun.com/j2ee/javaserverfaces/1.1/docs/tlddocs/index.html JSF 1.2 : http://java.sun.com/j2ee/javaserverfaces/1.2/docs/tlddocs/index.html JSF javadoc: JSF 1.1 : http://java.sun.com/j2ee/javaserverfaces/1.1/docs/api/index.html JSF 1.2 : http://java.sun.com/j2ee/javaserverfaces/1.2/docs/api/index.html Sun tutorial for J2EE 1.4 which includes a tutorial for JSF 1.1: http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html Sun tutorial for JEE 5.0 which includes a tutorial for JSF 1.2: http://java.sun.com/javaee/5/docs/tutorial/doc/index.html Facelets homepage: https://facelets.dev.java.net/ MyFaces homepage: http://myfaces.apache.org/index.html Oracle ADF : http://www.oracle.com/technology/products/jdev/htdocs/partners/addins/exchange/jsf/index.html
Practices
With this Exercice book, you'll learn to : How to setup a web application with JSF Create a CRUD (Create Read Update Delete) application Use advanced JSF technology like RichFaces of Facelet Create your first JSF project With this exercice, you are going to create the same JSF application as the one seen in the course. 1. Create a new JSF Projet 2. Check the configuration of your web.xml file 3. Create your javabean User 4. Declare your javabean in your faces-config.xml file. This one must be stored in the user session. 5. Create the subscription.jsp file. This page will ask a nane to the user. 6. Create the configuration.jsp file. This page will display the given name on the subscription.jsp file. 7. Create a new navigation rule in the faces-config.xml file. This rule must be declared to go from subscription.jsp file to confirmation.jsp file. 8. Check in your web.xml that your servlet-mapping for JSF match this pattern
<servlet-mapping> <servlet-name>Faces Servlet</servlet-name> <url-pattern>/faces/*</url-pattern> </servlet-mapping>
9. Launch your application Create the CRUD application Create all the business part of the application for creating a CRUD application. 1. Create a new JSF project on your EDI 2. Create a new class named Movie, in the com.labosun.jsf.entity package. This one is a javabean with the following attributes : long id String name String description java.util.Date creationDate
Page 97 of 100
17/10/09 18:17
int mark 3. Create the getters and the setters for theses attibutes. 4. Create a new interface in the com.labosun.jsf.dao package named IMovieDao. This one must have the following methods :
public public public public public Movie addMovie(Movie m); void updateMovie(Movie m); void removeMovie(Movie m); List<Movie> getAllMovies(); Movie findMovie(long id);
5. Create a new class in the com.labosun.jsf.dao.impl package named MemoryMovieDao. This class must implements the IMovieDao interface. 6. Implements all the methods like this :
private List<Movie> movieList; private long index = 1; public MemoryMovieDao() { this.movieList = new ArrayList<Movie>(); } public Movie addMovie(Movie m) { if (m != null) { m.setId(index++); movieList.add(m); } return m; } public void updateMovie(Movie m) { } public void removeMovie(Movie m) { if(movieList.contains(m)){ movieList.remove(m); } } public List<Movie> getAllMovies() { return movieList; } public Movie findMovie(long id) { for(Movie m : movieList){ if(m.getId() == id){ return m; } } return null; }
Create the navigations rules For the MovieManager project, you'll create the navigations rules. 1. Create 4 jsp files : index.jsp, add.jsp, list.jsp, edit.jsp. The index.jsp file must be an HTML redirection to the list.jsp file :
<meta http-equiv="Refresh" content="0;URL=faces/list.jsp">
2. Open the faces-config.xml file and try to realise theses navigations rules.
Your navigations rules should look like theses navigations rules :

<navigation-rule> <display-name>add</display-name> <from-view-id>/add.jsp</from-view-id> <navigation-case> <from-outcome>list</from-outcome> <to-view-id>/list.jsp</to-view-id>
Page 98 of 100
17/10/09 18:17
</navigation-case> </navigation-rule> <navigation-rule> <display-name>list</display-name> <from-view-id>/list.jsp</from-view-id> <navigation-case> <from-outcome>edit</from-outcome> <to-view-id>/edit.jsp</to-view-id> </navigation-case> </navigation-rule> <navigation-rule> <display-name>edit</display-name> <from-view-id>/edit.jsp</from-view-id> <navigation-case> <from-outcome>list</from-outcome> <to-view-id>/list.jsp</to-view-id> </navigation-case> </navigation-rule>
Implements the add method Let's create the web page to create a new Movie in your database. 1. In the com.labosun.jsf.managed package, you have to create a new Managed bean named MovieManaged and stored in the session to manipulate your created Movie (using the DAO layer : IMovieDao). In this managed bean, create 2 attributes : Movie addItem IMovieDao dao Create two methods : Table 1. Method public Movie getAddItem() Description This one will return the current instance of the item to add, if this one is non existing, this method have to create it
public String insert() This method will insert in the DAO layer, the current instance of the item to add
2. Create the add.jsp form with jsf markup. You have to provide fields to theses Movies's attributes : Name Description Author Example 1. Correction MovieManaged.java
package com.labosun.jsf.managed; import com.labosun.jsf.dao.IMovieDao; import com.labosun.jsf.dao.impl.MemoryMovieDao; import com.labosun.jsf.entity.Movie; /** * @author Yakanet */ public class MovieManaged { private Movie addItem; private IMovieDao dao; public MovieManaged() { dao = new MemoryMovieDao(); } ////// ADD PART /////// /** * Get the current item to add * @return */ public Movie getAddItem() { if(addItem == null) addItem = new Movie(); return addItem; } /** * Insert in the datasource with the add item * @return */ public String insert(){ dao.addMovie(getAddItem()); addItem = null; return "add"; } }
add.jsp
<%@page contentType="text/html" pageEncoding="UTF-8"%> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <%@ taglib prefix="h" uri="http://java.sun.com/jsf/html" %> <%@ taglib prefix="f" uri="http://java.sun.com/jsf/core" %>
Page 99 of 100
17/10/09 18:17
<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <title>JSP Page</title> <style type="text/css"> label{ float:left; width:150px; } </style> </head> <body> <f:view> <h:form> <h2>Add</h2> <div> <div> <h:outputLabel value="Name" for="name" /> <h:inputText id="name" value="#{movie.addItem.name}" /> </div> <div> <h:outputLabel value="Author" for="author" /> <h:inputText id="author" value="#{movie.addItem.author}" /> </div> <div> <h:outputLabel for="description" value="Description" /> <h:inputTextarea id="description" value="#{movie.addItem.description}" /> </div> <div> <h:commandButton action="#{movie.insert}" value="Add" /> <h:commandButton action="list" value="Cancel" immediate="true" /> </div> </div> </h:form> </f:view> </body> </html>
Realise the complete CRUD operations Let's add to the application the Read, Update, Delete operations In your managed bean, add the following methods : Table 2. Method public DataModel getModel(); public Movie getEditItem() public String edit() public String update() public void delete() Description Create if not existing a DataModel object containing all the created Movies Return the current editing object. This method create this object if it not existing. Set the current editing object Update the DAO layer with the current editing object. Delete in the DAO layout the selected item in the DataModel.
public int getNumberElement() Return the size of the existing movies in the DAO layer
Create some validation rules Manipulate the valudation rules and the life circle of JSF 1. In the add.js form, add a field Mark. This one must be linked to the mark attribute of the Movie class Add a validation constraint on this field (validateLongRange), the maks must be set with a number between 0 and 20 2. Add a validation constrain on the name field, this one must be required 3. Display all the error if one of theses constraints aren't respected 4. Add a cancel button to go on the list.jsp page 5. Do the same operations for the edit.jsp page Manipulate RichFaces Add some ajax features to your application 1. Get the richfaces libraries and add them to your web project. 2. In the list.jsp field use the RichFaces DataTable component to add some feature to the existing dataTable : Add a sort feature Add a datascroller to have only 5 items visible. 3. Add a rich calendar to the add.jsp page. 4. Add a rich inputNumberSlider to the add.jsp page. 5. Do the same for the edit.jsp page Use Facelet Realise the whole exercice with the facelet library Realise the whole exercice with the facelet library
Page 100 of 100

Sun Technologies: Java Enterprise Edition

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Sun Technologies: Java Enterprise Edition

Hochgeladen von

Copyright:

Verfügbare Formate

SUN TECHNOLOGIES: JAVA ENTERPRISE EDITION

When should you use EJB?