[fleXive]™ 3.1 Reference Documentation

The following required libraries have to be deployed:

Copy the following file from the extlib directory of your [fleXive] binary distribution to ${jboss.home}/server/default/lib:

To set up the databases do the following

Change to the flexive-dist directory of your [fleXive] distribution and run ant ear. This will create the flexive.ear file inside the flexive-dist directory. Copy flexive.ear to ${jboss.home}/server/default/deploy.

Flexive needs several libraries to be deployed to the application server's internal lib directories. Execute these steps once glassfish has been setup.

Setting up Glassfish

Starting Glassfish

Three connection pools, two for the division (transactional and non-transactional) and one for the configuration database, have to be set up.

For MySQL copy and paste the following data-source definitions to a file (e.g. flexive-ds.xml) and update your database connection settings:

                <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE resources PUBLIC "-//Sun Microsystems Inc.//DTD Application Server 9.0 Domain//EN" "sun-resources_1_3.dtd">
<resources>
    <!--
        Glassfish MySQL datasource configuration

        To add these datasource, start Glassfish v2, and execute
        ${glassfish.home}/bin/asadmin add-resources /path/to/flexive-mysql-ds.xml

        Please make sure mysql-connector-java-<version>-bin.jar is located in /domains/domain1/lib/ext (adapt the path to match your domain)
    -->

    <!-- Configure the global configuration datasource -->
    
    <jdbc-connection-pool
        name="flexiveConfiguration"
        datasource-classname="com.mysql.jdbc.jdbc2.optional.MysqlXADataSource"
        res-type="javax.sql.XADataSource"
		non-transactional-connections="false">
        <property name="user" value="root"/>
        <property name="password" value="a"/>
        <property name="url" value="jdbc:mysql://localhost:3306/flexiveConfiguration?useUnicode=true&amp;characterEncoding=utf8&amp;characterResultSets=utf8"/>
    </jdbc-connection-pool>

    <jdbc-resource pool-name="flexiveConfiguration" jndi-name="jdbc/flexiveConfiguration" enabled="true" object-type="user"/>


    <!-- Configure the first flexive division -->

    <jdbc-connection-pool
        name="flexiveDivision1"
        datasource-classname="com.mysql.jdbc.jdbc2.optional.MysqlXADataSource"
        res-type="javax.sql.XADataSource"
		non-transactional-connections="false">
        <property name="user" value="root"/>
        <property name="password" value="a"/>
        <property name="url" value="jdbc:mysql://localhost:3306/flexive?useUnicode=true&amp;characterEncoding=utf8&amp;characterResultSets=utf8"/>
    </jdbc-connection-pool>

    <jdbc-resource pool-name="flexiveDivision1" jndi-name="jdbc/flexiveDivision1" enabled="true" object-type="user"/>

    <!-- Configure the first flexive division non-XA datasource -->

    <jdbc-connection-pool
        name="flexiveDivision1NoTX"
        datasource-classname="com.mysql.jdbc.jdbc2.optional.MysqlDataSource"
        res-type="javax.sql.DataSource"
		non-transactional-connections="true">
        <property name="user" value="root"/>
        <property name="password" value="a"/>
        <property name="url" value="jdbc:mysql://localhost:3306/flexive?useUnicode=true&amp;characterEncoding=utf8&amp;characterResultSets=utf8"/>
    </jdbc-connection-pool>

    <jdbc-resource pool-name="flexiveDivision1NoTX" jndi-name="jdbc/flexiveDivision1NoTX" enabled="true" object-type="user"/>

</resources>
            

Respectively apply these settings for H2:

                <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE resources PUBLIC "-//Sun Microsystems Inc.//DTD Application Server 9.0 Domain//EN" "sun-resources_1_3.dtd">
<resources>
    <!--
        Glassfish H2 datasource configuration

        To add these datasource, start Glassfish v2, and execute
        ${glassfish.home}/bin/asadmin add-resources /path/to/flexive-h2-ds.xml

        Please make sure h2.jar is located in /domains/domain1/lib/ext (adapt the path to match your domain)
    -->

    <!-- Configure the global configuration datasource -->
    
    <jdbc-connection-pool
        name="flexiveConfiguration"
        datasource-classname="org.h2.jdbcx.JdbcDataSource"
        res-type="javax.sql.XADataSource"
		non-transactional-connections="false">
        <property name="user" value="sa"/>
        <property name="password" value="()"/>
        <property name="url" value="jdbc:h2:tcp://localhost:9092/~/flexiveConfiguration;MVCC=TRUE"/>
    </jdbc-connection-pool>

    <jdbc-resource pool-name="flexiveConfiguration" jndi-name="jdbc/flexiveConfiguration" enabled="true" object-type="user"/>


    <!-- Configure the first flexive division -->

    <jdbc-connection-pool
        name="flexiveDivision1"
        datasource-classname="org.h2.jdbcx.JdbcDataSource"
        res-type="javax.sql.XADataSource"
		non-transactional-connections="false">
        <property name="user" value="sa"/>
        <property name="password" value="()"/>
        <property name="url" value="jdbc:h2:tcp://localhost:9092/~/flexive;SCHEMA=flexive;MVCC=TRUE;LOCK_TIMEOUT=10000"/>
    </jdbc-connection-pool>

    <jdbc-resource pool-name="flexiveDivision1" jndi-name="jdbc/flexiveDivision1" enabled="true" object-type="user"/>

    <!-- Configure the first flexive division non-XA datasource -->
    <jdbc-connection-pool
        name="flexiveDivision1NoTX"
        datasource-classname="org.h2.jdbcx.JdbcDataSource"
        res-type="javax.sql.DataSource"
		non-transactional-connections="true">
        <property name="user" value="sa"/>
        <property name="password" value="()"/>
        <property name="url" value="jdbc:h2:tcp://localhost:9092/~/flexive;SCHEMA=flexive;MVCC=TRUE;LOCK_TIMEOUT=10000"/>
    </jdbc-connection-pool>

    <jdbc-resource pool-name="flexiveDivision1NoTX" jndi-name="jdbc/flexiveDivision1NoTX" enabled="true" object-type="user"/>

</resources>
            

While Glassfish is running, execute ${glassfish.home}/bin/asadmin add-resources /path/to/flexive-ds.xml to create the connection pools and JDBC resources for MySQL or ${glassfish.home}/bin/asadmin add-resources /path/to/flexive-h2-ds.xml if you are using the H2 database. You have to pass the absolute path to your XML file, otherwise Glassfish looks in its own config directory.

Should you need to edit or reset your datasources, you can do so in the Glassfish administration console under Resources → JDBC.

Change to the flexive-dist directory of your [fleXive] distribution and run ant ear. This will create the flexive.ear file inside the flexive-dist directory.

Using the autodeploy directory:

Using the Admin UI:

In order to run JBossCache on Linux IPv4 needs to be defined as the preferred IP stack. In the Glassfish admin console, go to Application Server → JVM Settings → JVM Options and add the following option:

The next step is to define a JSF bean that provides the blog postings to be shown on the front page of our application. We create a managed bean under src/java/war, which will be automatically compiled and packaged into the WAR archive.

In the resources/META-INF directory you find the configuration files for the (web) application. Since the provided web.xml already uses sensible defaults for running [fleXive] applications, all you need to do is register your JSF bean in resources/META-INF/faces-config.xml and add navigation rules between the overview and the create page:

    <managed-bean>
        <managed-bean-name>helloWorldBean</managed-bean-name>
        <managed-bean-class>HelloWorldBean</managed-bean-class>
        <managed-bean-scope>request</managed-bean-scope>
    </managed-bean>

    <!--  A navigation rule for our input mask, if the content is saved successfully,
     "success" is returned, which leads to a direct rendering and response
     of the index.xhtml view. The entries made via the input mask are shown
     in this view. -->
    <navigation-rule>
        <from-view-id>/create.xhtml</from-view-id>
        <navigation-case>
            <display-name>success</display-name>
            <from-outcome>success</from-outcome>
            <to-view-id>/index.xhtml</to-view-id>
        </navigation-case>
    </navigation-rule>

You can find the datastructures of the hello-world application in the administration GUI's structure editor. Log on to the administration GUI and expand the tab named "Structure". flexive/adm/ You should be able to see the type Blog Entry in the tree. Expand it and click on one of the properties. In the "Edit Property Assignment" tab in the right frame you can see the properties originally set in the hello001.groovy script.

The most interesting parts of this tutorial are the overview and upload pages. On the first we display all uploaded document objects, the latter allows the user to upload new files or edit existing ones.

The index page of the application renders a link to an empty upload form for uploading new document, and also renders all document objects already uploaded. Note that in the first version of the tutorial, security is completely disabled, thus every user can see and edit all document objects in the system.

Our web/index.xhtml lists all available documents and adds a link to the upload form.

                    <!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:fx="http://www.flexive.com/jsf/core">
<head>
    <!-- Add flexive includes -->
    <fx:includes/>

    <!-- Add our own stylesheet for the result page -->
    <link rel="stylesheet" type="text/css" href="css/tutorial01.css"/>
</head>

<body>
<!-- Output JSF error or info messages here -->
<h:messages globalOnly="true"/>

<p class="message">
    Welcome to tutorial 1 - the first version of our document data store.
</p>

<!-- The main menu -->
<ul id="mainmenu">
    <li>
        <h:outputLink value="upload.xhtml">Upload document</h:outputLink>
    </li>
</ul>

<!-- Render all available document objects, provided by #{tutorialBean.documents} -->
<h:form id="frm">
    <ul class="documents">

        <!-- Iterate over all document objects -->
        <ui:repeat var="row" value="#{tutorialBean.documents}">
            <li>
                <!-- Render the file (preview image) -->
                <fx:resultValue id="preview" value="#{row[1]}"/>

                <!-- Render the document caption -->
                    <span class="caption">
                        <fx:resultValue id="caption" value="#{row[2]}"/>
                    </span>

                <!-- Add an edit button below the image -->
                <h:commandLink action="edit" styleClass="editButton">
                    <!--
                        Load the content instance of the current row and store it in
                        #{fxContentViewBean.content}. The edit page will then use this
                        content instance.
                        Note that this listener will only be fired when the user actually
                        clicks on the commandLink.
                    -->
                    <f:setPropertyActionListener target="#{fxContentViewBean.content}"
                                                 value="#{fxSystemBean.content[row[0]]}"/>
                    Edit...
                </h:commandLink>
            </li>
        </ui:repeat>
    </ul>
</h:form>

<p style="clear:both; padding-top:25px;"><h:outputLink
        onclick="window.open('http://wiki.flexive.org/confluence/display/FX/Generating+thumbnails', 'In_depth_explanation', 'width=950,height=600,left=50,top=200,scrollbars=yes,resizable=yes');"
        value="#">
    What happens on this page?
</h:outputLink>
</p>

</body>
</html>
                

Like in the previous tutorial, we add a simple JSF managed bean that provides our search results.

                package com.flexive.examples.tutorial01;

import com.flexive.faces.model.FxResultSetDataModel;
import com.flexive.shared.exceptions.FxApplicationException;
import com.flexive.shared.search.FxResultSet;
import com.flexive.shared.search.SortDirection;
import com.flexive.shared.search.query.SqlQueryBuilder;

import javax.faces.model.DataModel;

/**
 * JSF managed bean for the tutorial01 application.
 *
 * @author Daniel Lichtenberger (daniel.lichtenberger@flexive.com), UCS - unique computing solutions gmbh (http://www.ucs.at)
 * @version $Rev: 469 $
 */
public class Tutorial01Bean {
    private DataModel documents;

    public DataModel getDocuments() throws FxApplicationException {
        if (documents == null) {
            final FxResultSet result = new SqlQueryBuilder()
                    .select("@pk", "document01/file", "caption", "created_at")
                    .type("document01")
                    .orderBy("created_at", SortDirection.DESCENDING)
                    .getResult();
            documents = new FxResultSetDataModel(result);
        }
        return documents;
    }
}

            

To serve the image URLs rendered by <fx:resultValue> to the browser, we need a servlet providing those images. For this purpose, you have to add the [fleXive] thumbnail servlet to your web.xml.

<servlet>
    <servlet-name>Thumbnail</servlet-name>
    <servlet-class>com.flexive.war.servlet.ThumbnailServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
    <servlet-name>Thumbnail</servlet-name>
    <url-pattern>/thumbnail/*</url-pattern>
</servlet-mapping>

The [fleXive] template project's web.xml already includes this mapping.

Finally, we have to register the data provider bean and provide navigation routes for our buttons and links in the faces-config.xml:

                    <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faces-config
        PUBLIC "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN"
        "http://java.sun.com/dtd/web-facesconfig_1_0.dtd">
<faces-config>
    <!-- Facelets View Handler Definition. Never remove this one. -->
    <application>
        <view-handler>
            com.sun.facelets.FaceletViewHandler
        </view-handler>
    </application>

    <!-- Define our managed bean -->
    <managed-bean>
        <managed-bean-name>tutorialBean</managed-bean-name>
        <managed-bean-class>com.flexive.examples.tutorial01.Tutorial01Bean</managed-bean-class>
        <managed-bean-scope>request</managed-bean-scope>
    </managed-bean>

    <!-- Return to overview page if upload was successful -->
    <navigation-rule>
        <from-view-id>/upload.xhtml</from-view-id>
        <navigation-case>
            <from-outcome>success</from-outcome>
            <to-view-id>/index.xhtml</to-view-id>
        </navigation-case>
    </navigation-rule>

    <!-- Open editor from index page -->
    <navigation-rule>
        <from-view-id>/index.xhtml</from-view-id>
        <navigation-case>
            <from-outcome>edit</from-outcome>
            <to-view-id>/upload.xhtml</to-view-id>
        </navigation-case>
    </navigation-rule>
</faces-config>

                

Before proceeding to create a new [fleXive] application, make sure you have a working build system, i.e. at least

The blank [fleXive] application includes an example EJB and JSF bean that shows the intended use of the package structure, cfe stands for com.flexive.example:

You can remove the example beans if you like, or rename them and use them as a start for your own beans (if any).

A [fleXive] application is a collection of JAR files that follow a few naming conventions that will be packaged into an EAR archive. Note that each file is optional, so if you for example don't provide EJB3 beans, you don't need to provide a -ejb.jar file.

Archetypes provide a quick start for new projects. Currently we offer a archetype for a full enterprise application with web and console frontends. Since the archetype includes setup scripts for the H2 database, it can be used without external dependencies like MySQL. However, for administration tasks such as database setup you currently have to use the tools provided by the [fleXive] distribution.

Creating a user requires special rights. More precisely only callers (i.e. a user) in role ACCOUNT MANAGEMENT may create users, and only for their mandator. An exception is a user in the role GLOBAL_SUPERVISOR who may create users for all mandators. An example of how to create a new user is given next.

[fleXive] provides two methods for updating an account. One is for updating only some personal data of the specified user (name, login name, password, e-mail address, and language). The other one lets you update all attributes of the user. For both methods applies: setting one parameter to null in the method call means keeping its original value (i.e. the value of the corresponding account attribute is not changed).

The following code updates the previously created administrator account (ID 1) by setting its name to “System administrator” and its e-mail address to “sysadmin@flexive.org”.

There are two prerequisites for the caller to remove an account:

GlobalSupervisor may remove users belonging to any mandator. The accounts USER_GUEST and USER_GLOBAL_SUPERVISOR may not be removed in any case.

For removing an account one only needs to know the account ID. Thus removing the previously created and updated administrator account works as follows:

Authentication is currently performed against the database by calling FxContext.login(..) (or as an alternative directly using AccountEngine.login(..)). JAAS based login can be implemented very easily by uncommenting some code in LoginLogoutHandler. It is planned to make this configurable in future versions of [fleXive].

At the core and web layer (provided they run in the same virtual machine) a context is available which is stored in a ThreadLocal called FxContext which provides amongst others the following information:

The UserTicket is the central class providing information about the current user ranging from the user name, mandator, user group memberships, assigned roles to all access control lists the user belongs to indirectly. Hence it serves as the central authorization data provider for any security check performed.

[fleXive] was designed to be used by application service providers (ASP) with only one deployed enterprise application instance using multiple databases. These database instances are called Divisions and contain their own accounts, structures and content - totally separated from other users of [fleXive].

Roles can be assigned individually to users and groups. Every user (or account) is eligible to use any role assigned to the user or any group he belongs to. It is considered best practice to assign roles to groups and only in very rare cases (e.g. flagging someone as a global supervisor) should the role assignments be done on an individual (per user) basis.

[fleXive] provides the following roles:

A good analogy to explain how structures in [fleXive] are organised are classes and object instances: a class in an object oriented programming language describes which attributes (in [fleXive] called properties) are available. If an attribute itself acts like a container for other attributes we call it a group. We call the class analogon Type (implemented in the class FxType), attributes property (implemented in FxProperty) and a collection of attributes Group (implemented in FxGroup).

A type, identified by its name, defines behaviour (what kind of permissions may be applied, storage model or language mode is to be used, etc.) and structure (properties and groups are assigned to types).

Every data type can potentially support values for different languages - depending on the properties' and property assignments' multilingual support settings.

Working with binary content is like working with ordinary input- and outputstreams in Java. For uploading a binary an InputStream and for downloading an OutputStream has to be passed. Transfer of binaries is handled by [fleXive]'s own streaming framework fxStream. It uses nonblocking tcp sockets as transport medium if the client and server part exist in different virtual machines and is able to detect if they run within the same VM for optimal performance.

Select lists usually contain a set of related select items, which are used in GUIs to enable the user to make a selection of one or more of these items. [fleXive] allows in-memory creation of slim select lists for quick GUI display, as well as defining and persisting fully fledged deeply nested select lists. Names of selectlist items have to be unique within their respective list.

Multiplicity - or often referred to as cardinality - defines the minimum and maximum occurance of an assignment. An assignment in the context of [fleXive] is a group- or a property assignment. Multiplictiy is implemented in the class FxMultiplicity which contains some predefined and often used constants:

The value N means any number of occurances.

A multiplicity of 1 to 5 elements would be coded like this: new FxMultiplicity(1,5)

A property defines a name and a datatype (and some options). It can only exist (and is of relevance) if it is assigned to a type or group. The purpose of keeping properties and their assignments separate is the ability to share them and query across multiple types with a single property.

There are two ways to assign a property to an existing type or group: Either by calling FxPropertyEdit.createNew(..) method which can clone existing or create entirely new properties or by reusing an existing property assignment by calling FxPropertyAssignmentEdit.createNew(..).

To reuse an existing property-assignment is even simpler:

A group basically only defines a name (and some options). It can only exist (and is of relevance) if it is assigned to a type or another group. The purpose of keeping groups and their assignments separate is the ability to share them and be consistent with how properties and property assignments are handled.

Just like using properties, there are two ways to assign a group to an existing type or another group: Either by calling FxGroupEdit.createNew(..) method which can clone existing or create entirely new groups or by reusing an existing group assignment by calling FxGroupAssignmentEdit.createNew(..).

Both properties and groups allow the definition of options. These options can hold any arbitrary String or Boolean value and, if defined, the assignments to the property or group may override the value. The name of an option must be unique. See the API documentation of class FxStructureOption for more details.

The following options are currently actively supported: