Version 10

    This is now in Seam from the 1.2.1.GA release.



    Latest version: 0.1-draft, compatible with > Seam 1.1.5.GA




    Getting Started Guide - Using s:selectItems & ec:convertEntity with EJB3 Entities


    1. Download and Configure SeamEntityConverter

      1. Download the, and unzip it.  Included are prebuilt jars, source code and an example

      2. Place entityconverter.jar in the WEB-INF/lib of your war

      3. Make sure you have a Seam-managed persistence context set up (see Chapter 8.3.1 of the reference documentation) with entityManager as the name, and are using it to manage your entities.

    2. Ensure your Entity Beans and Action beans are setup correctly

      1. Make sure you have the correct relationships between your entities (i.e. use the @ManyToOne, @OneToOne etc. annotations)

      2. Make sure you are outjecting a list of entities (NOT a List<SelectItem>)

    3. Alter your page

      1. Include the taglibrary definition in your page.  The uri of the taglibrary is but its broken!.

        1. If you are using facelets add xmlns:ec="" to your root tag (probably ui:composition)

        2. If you are using JSP add <%@ taglib uri="" prefix="ec"%> to the top of the file

      2. Add a select JSF component (e.g. h:selectOneMenu)

      3. Make sure you use s:selectItems rather than f:selectItems (see Code Block 1 below)

        1. Add the value attribute, with an EL expression referencing the outjected list you want to display

        2. Add the var attribute; this must be a static text variable

        3. Add the label attribute to set the label for each item in the dropdown.  You will probably want to reference the var attribute

        4. Add the <ec:convertEntity /> tag to the


    Code Blocks


    Code Block 1: Example use of si:selectItems

    <h:selectOneMenu value="#{user.nationality}">
       <s:selectItems value="#{nationalities}" var="nationality" label="#{nationality.label}" ></s:selectItems>
       <ec:convertEntity ></ec:convertEntity>




    Examples Explained


    The examples show a number of common cases for the use of SeamEntityConverter.  The example code described here applies equally to the facelets and the jsp example.  Make sure you look at the example code when reading this section!




    <h:selectOneListbox value="#{client.clientType}">
       <s:selectItems value="#{clientTypes.resultList}" var="clientType" label="#{clientType.description}" noSelectionLabel="Please Select..." ></s:selectItems>
       <ec:convertEntity ></ec:convertEntity>


    ClientType shows the standard use of ec:convertEntity with s:selectItems/




    <h:selectManyListbox value="#{client.factories}">
       <s:selectItems value="#{factories.resultList}" var="factory" label="#{factory.manager} (#{factory.capacity})" ></s:selectItems>
       <ec:convertEntity entityClass="org.jboss.seam.example.entityconverter.Factory" ></ec:convertEntity>


    Factory is a select many, which works just as a select one.  Note, that due to a limitation in the entityConverter you must specify the class of the entity to be converted.


    Using EJB-Queries with s:selectItems


    The combination of s:selectItems, ec:convertEntity and Seam's EntityQuery's from the Seam Application framework is really powerful. Imagine you have these entities:


    public class Department {
       private Integer id;
       private String name;
       // other properties
       // getters & setters


    public class Employee {
       private Integer id;
       private Department department;
       // other properties
       // getters & setters


    If you create or edit the record of an employee, you want to set the department. This list of available departments has to be fetched from the database. You can do this by defining a query object in components.xml:


    <framework:entity-query name="departments" ejbql="select d from Department d" ></framework:entity-query>


    Now you can use the seam component "departments" with the s:selectitems tag:


    <h:selectOneMenu value="#{employee.department}">
       <s:selectItems value="#{departments.resultList}" var="department" label="#{}"></s:selectItems>
       <ec:convertEntity ></ec:convertEntity>




    Reference Guide




    • s:convertEntity Attaches the org.jboss.seam.EntityConverter to the Select{One, Many}

      • entityClass attribute sets the class of the entities being converted. Only required if the converter is having problems guessing the class. (static value only)




    • org.jboss.seam.EntityConverter - A generic converter which can deal with all objects marked with @Entity which have primitive, primitive-wrapped or String ids.


    Abstract Converters

    • org.jboss.seam.entityconverter.AbstractEntityConverter. This converter will do most of the work if you have a more complex id. You just need to:

      • Override getIdAsString, and provide conversion from the entities Id to a string

      • Override getIdAsObject, and provide conversion from a string back to an Id


    Configuration through components.xml


    You can change the EntityManager used in conversion by altering the lookup component used in components.xml:


    <component name="org.jboss.seam.entityconverter.lookup">
       <property name="entityManager">#{myEntityManager}</property>


    If you need to use different EntityManagers then you can configure an alternative:


    <component name="myLookup" class="org.jboss.seam.entityconverter.Lookup">
       <property name="entityManager">#{anotherEntityManager}</property>


    <ec:convertEntity lookup="#{myLookup"} ></ec:convertEntity>




    0.1 - Initial release of fork from SeamSelectItemsNewDesign





    • Original Design - SeamSelectItemsNewDesign