[fleXive]™ 3.0 Reference Documentation

Revision 1630, 2009/09/16 12:49

Authors:

Johannes Wernig-Pichler <>
Anton Zrzavy <>

Table of Contents

1. Introduction
2. Installing [fleXive]
Prerequisites
To run [fleXive] and develop [fleXive] applications you need...
To develop [fleXive] you need...
[fleXive] installation guide for JBoss 4.2.2 GA
Required libraries
System configuration
Database Setup
Deployment
Starting [fleXive]
Refining your configuration
[fleXive] installation guide for Glassfish V2
Required libraries
Running the ant task
Database Setup
Setting up and starting Glassfish
Creating the Connection pools
Deployment
Building [fleXive] from source
Troubleshooting
Multiple JBoss installations
JBossCache, Linux and IPv6
Apache ANT
3. The [fleXive] Tutorial
Your first [fleXive] application
Defining the data model
Retrieving data from the database
Building the graphical user interface
Deployment descriptor and JSF configuration
Compiling and deploying the application
Preview of the Backend Administration
Tutorial 1: The Document Store Application
Defining the data model
The document browser and upload pages
Using <fx:resultValue>
Passing content instances to the editor form
The upload form
Retrieving data from the database
Rendering previews: the ThumbnailServlet
Wiring up the faces configuration
Compiling and deploying the application
4. Writing [fleXive] applications
The [fleXive] distribution
Getting started
IDE integration
Eclipse
IntelliJ IDEA
Programming [fleXive]
Package for distribution
Build file support
Build targets
Building applications with Apache Maven
The [fleXive] Maven repository
Project archetypes
The EAR archetype
[fleXive] artifacts
5. The big picture
6. The [fleXive] core components
User Management
Creating a user
Updating a user
Removing a user
Security
Overview
Authentication / FxContext / UserTickets
Divisions
Mandators
ACLs - Access Control Lists
Role Based Security
Structure Engine
Overview
Types
Root Type
Type parameters
Creating a new type
Data types
Handling binary content
Select lists
Select list parameters
Select list item parameters
Select list creation and persistance
Select list item permissions
Multiplicity
Properties and property assignments
Property parameters
Uniqueness of values
Groups and group assignments
Group parameters
Group modes
Property and group options
Content Engine
Overview
Using FxContent
Primary keys and versions
Search Engine
An introduction to FxSQL
Select user-defined columns
Select all columns
Fulltext search
Properties versus assignments
Content permissions
Tree Search
Date and Time Functions
Resolving system properties
Filters
Order by
Comments
Operator table
Literal value formatting
SqlQueryBuilder: Building queries in Java
Conditions
Filters
Nested conditions
Search parameters
The Groovy query builder
Working with search results
Accessing result rows
Projections
Tree Engine
Security
Scripting
Edit and Live modes
Examples
Scripting Engine
Overview
Events and Bindings
Run-Once and Startup Scripts
Workflow Engine
Conceptual Overview
Creating and updating workflows
Configuration Engine
Conceptual Overview
Working with configuration parameters
Object parameters
7. JSF Support
The [fleXive] component library
Using the component library
Content manipulation
<fx:content>
<fx:children>
<fx:value>
<fx:fxValueInput>
<fx:fxValueInputLanguageSelect>
<fx:resultValue>
<fx:contentList>
<fx:thumbnail>
<fx:resultTable>
<fx:resultTableUpdater>
<fx:colorPicker>
Framework components
<fx:includes>
<fx:yuiSetup>
Form utility components
<fx:formRow>
<fx:fieldSet>
JSF managed beans
fxContentViewBean
fxAuthenticationBean
fxMessageBean
Delivering XHTML pages from the classpath
URI rewriting for contents
Writing reusable [fleXive] components
JSF components
Build file support
Deployment
Packaging
EJB components
The JSF plugin API
Overview
The plugin registry
Registering plugins at extension points
8. JBoss Seam and [fleXive]
Integration guide
Programming [fleXive] in Seam
Authorization and Authentication
9. The [fleXive] administration GUI
Running the administration GUI
The structure editor
The structure editor GUI
Structure tree items
Structure tree interaction
View mode vs. edit mode
The type editor
The group editor
The property editor
The script assignment Editor
The instance editor
Creating and editing contents
The content tree
Modes of the content tree
The content tree's context menu
The query editor
Creating queries with the visual query editor
Query results
Saved queries and briefcases
The FxSQL Search
User account administration
Creating a user
The user account overview
User group administration
The user group overview
Mandator administration
Creating a mandator
The mandator overview
ACL administration
Creating an ACL
The permission matrix
The ACL overview
Workflow administration
Step definitions
Creating a workflow
The workflow overview
Script administration
Creating a script
The script overview
The Script Console
System information and language settings
The System Information
Language settings
Select list administration
Creating a select list
Editing a select list
10. [fleXive] Plugins
Core JSF components
Global Configuration Plugin
Usage
Backend Feedback Plugin
Glossary
Bibliography

List of Figures

3.1. The document store application, version 1

List of Tables

6.1. Account Attributes
6.2. [fleXive] structure elements
6.3. FxTypeEdit parameters
6.4. [fleXive] data types
6.5. FxSelectList parameters
6.6. FxSelectListItem parameters
6.7. Relevant permissions for working with select list items
6.8. FxPropertyEdit/FxPropertyAssignmentEdit shared parameters
6.9. FxPropertyEdit exclusive parameters
6.10. FxPropertyAssignmentEdit exclusive parameters
6.11. FxGroupEdit/FxGroupAssignmentEdit shared parameters
6.12. FxGroupEdit exclusive parameters
6.13. FxGroupAssignmentEdit exclusive parameters
6.14. Supported options
6.15. XPath to value mapping
6.16. Date and Time functions provided in FxSQL
6.17. System property fields provided in FxSQL
6.18. FxSQL operator table
6.19. FxSQL literal value formats
9.1. FxScriptEvent list

List of Examples

6.1. Creating a new user
6.2. Updating a user
6.3. Removing a user
6.4. Creating a new FxType
6.5. Creating a new FxType using the GroovyTypeBuilder
6.6. Handling binary content
6.7. Creating new properties
6.8. Reusing property assignments
6.9. Creating a new group
6.10. Creating a new group using the GroovyTypeBuilder
6.11. Creating a "Person" type
6.12. Creating "Person" instances
6.13. Creating a nested query
6.14. Specifying a query with the GroovyQueryBuilder
6.15. Iterating over a FxResultSet
6.16. Directly accessing the search results using getRows()
6.17. Creating a new tree node attached to the root node
6.18. Clear both Live and Edit Tree in the groovy console
6.19. Creating a workflow step definition
6.20. Creating a new workflow with steps and routes
7.1. Render FxContent property values
7.2. Edit an existing FxContent instance
7.3. Create a new FxContent instance
7.4. Add values to properties with multiplicities
7.5. Add a new empty group to a content instance
7.6. Use InputMappers for application-specific properties
7.7. Iterating over property values
7.8. Iterating over group values and nested iterators
7.9. An input row for editing a FxString value
7.10. An autocomplete handler for user names
7.11. Writing custom autocomplete handlers
7.12. Using fx:resultTable to submit and render FxSQL queries
7.13. Updating a resultTable through an Ajax4jsf update
7.14. Using the color picker with a JSF input component
7.15. Using the color picker for a form input
7.16. Rendering a plain text input row
7.17. A fieldset with two formrow elements
7.18. Making a [fleXive] application extensible
7.19. Writing a plugin for a [fleXive] application
7.20. Specifying a PluginFactory in flexive-plugins-config.xml

Managing and operating on hierarchical data structures is an issue in many projects, alongside with security concerns, versioning and querying. Till now, neither open nor closed source projects or frameworks offer possibilities to dynamically define and manipulate the structure of hierarchical data in a scope like [fleXive]. Hence the urge to provide a solution that combines flexibility, security and performance in one customizable package.

[fleXive] is a JavaEE 5 open-source (LGPL) framework for the development of complex and evolving (web-)applications. It speeds up development as it handles numerous important application issues and keeps your application flexible over the development-cycle. It is based on the lastest industry-standards like EJB 3, JSF, etc.

The [fleXive] backend application is an optional application built on top of the framework and is licensed under the GNU General Public License (GPL). It helps you to visually manage most aspects of [fleXive] - like defining data structures, building queries, manage users and security, etc.

[fleXive] concentrates on enterprise-scale content storage and retrieval, and includes comprehensive JSF support for displaying and manipulating these contents in web applications. The runtime environment can be included in existing JavaEE applications, but you can also build new applications and package them into stand-alone JavaEE applications. Our emphasis lies on the runtime environment, so if you are looking e.g. for tool-driven JSF development, take a look at the popular JBoss Seam framework and embed the [fleXive] runtime environment in that project.

The goal of [fleXive] is to relieve you from many tendious and repetitive programming tasks when building secure, data-centric (web-)applications.

If you are new to [fleXive] please use the following tools to get started:

  1. The [fleXive] website will provide you with top-level information about [fleXive]. Have a look at the "Explore [fleXive]" section.

  2. This reference documentation will provide all information to use [fleXive] for the development of your application.

  3. In the [fleXive] wiki you will find more tutorials, HowTo's, samples and developer infos

  4. FAQ's are anwered on the [fleXive] website

For questions, use the [fleXive] forum and mailinglists. We also provide a issue trackings system for bug reports and feature requests. In case you are interested in the development of [fleXive], have a look at the Development Section on the [fleXive] website and join the developer mailinglist.

[fleXive] is a Professional Open Source project. UCS - unique computing solutions gmbh (http://www.ucs.at) offers commercial development support and training for [fleXive].

  1. Administrator privileges on your machine

  2. The Sun Java 6 Platform, Standard Edition Development Kit

    1. Set your JAVA_HOME and JDK_HOME environment variable to your JDK root directory (e.g. JAVA_HOME=/usr/lib/jvm/java-6-sun on Linux, C:\Java\jdk1.6.0_03 on Windows)
  3. An application server ( JBoss or Glassfish) with EJB3 support

    1. Either download and install JBoss 4.2.2.GA or later ( ${jboss.home} denotes your JBoss installation directory)
    2. or download and install Glassfish V2 or later ( ${glassfish.home} denotes your Glassfish installation directory)
  4. A database (at the moment only MySql is supported)

    Download and install MySql 5.0 or later

    Currently, choosing UTF-8 as the default charset causes issues with the database setup scripts. Use the default setting (Latin1) instead.

  5. ImageMagick version 6.3.4 or later (optional)

  6. Apache ANT 1.7 and the ant-optional package

  7. A [fleXive] binary distribution or the [fleXive] source code, if you want to build [fleXive] from source

If you are interested in developing [fleXive], you will need the [fleXive] source code and an IDE like Eclipse or a proprietary solution.

The following sections are good starting points for future [fleXive] developers:

We provide the current generated [fleXive] API Documentation for you on our website.

  • Create and copy the datasource config file flexive-ds.xml to ${jboss.home}/server/default/deploy/ and adapt to your datasource(s) or simply copy it from the [fleXive] source tree, if available. In the flexive-ds.xml configure your database connections as follows: For the flexive database

    <!-- transactional datasource -->
    <xa-datasource>
        <jndi-name>jdbc/flexiveDivision1</jndi-name>
        <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
        <!-- Note: "&amp;" has to be used instead of "&" for parameters -->
        <xa-datasource-property name="URL">jdbc:mysql://localhost:3306/flexive?useUnicode=true&characterEncoding=utf8&characterResultSets=utf8</xa-datasource-property>
        <user-name>root</user-name>
        <password>a</password>
    </xa-datasource>
    
    <!-- non-transactional datasource for database structure patches, Quartz, etc. -->
    <no-tx-datasource>
        <jndi-name>jdbc/flexiveDivision1NoTX</jndi-name>
        <driver-class>com.mysql.jdbc.Driver</driver-class>
        <!-- Note: "&amp;" has to be used instead of "&" for parameters -->
        <connection-url>jdbc:mysql://localhost:3306/flexive?useUnicode=true&characterEncoding=utf8&characterResultSets=utf8</xa-datasource-property>
        <user-name>root</user-name>
        <password>a</password>
    </no-tx-datasource>
    
    

    For the flexiveConfiguration database

    <xa-datasource>
        <jndi-name>jdbc/flexiveConfiguration</jndi-name>
        <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
        <!-- Note: "&amp;" has to be used instead of "&" for parameters -->
        <xa-datasource-property name="URL">jdbc:mysql://localhost:3306/flexiveConfiguration?useUnicode=true&characterEncoding=utf8&characterResultSets=utf8</xa-datasource-property>
        <user-name>root</user-name>
        <password>a</password>
    </xa-datasource>
    

    flexive-ds.xml

                                    
    <!--
     JBoss Datasource Configuration
    
     See http://www.redhat.com/docs/manuals/jboss/jboss-eap-4.3/doc/Server_Configuration_Guide/html/Connectors_on_JBoss-Configuring_JDBC_DataSources.html
     for detailed configuration infos
    -->
    <datasources>
    
        <!--
            transactional datasource, as configured in the global configuration
        -->
        <xa-datasource>
            <jndi-name>jdbc/flexiveDivision1</jndi-name>
            <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
            <!-- Note: "&amp;" has to be used instead of "&" for parameters -->
            <xa-datasource-property name="URL">jdbc:mysql://localhost:3306/flexive?useUnicode=true&amp;characterEncoding=utf8&amp;characterResultSets=utf8</xa-datasource-property>
            <user-name>root</user-name>
            <password>a</password>
    
            <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
            <no-tx-separate-pools/>
            <!-- This disables transaction interleaving (which BTW, most DB vendors don't support) -->
            <track-connection-by-tx/>
            <isSameRM-override-value>false</isSameRM-override-value>
    
            <!--pooling parameters-->
            <min-pool-size>5</min-pool-size>
            <max-pool-size>20</max-pool-size>
            <blocking-timeout-millis>5000</blocking-timeout-millis>
            <idle-timeout-minutes>15</idle-timeout-minutes>
    
            <!-- If you supply the usr/pw from a JAAS login module -->
            <security-domain/>
    
            <exception-sorter-class-name>
                com.mysql.jdbc.integration.jboss.ExtendedMysqlExceptionSorter
            </exception-sorter-class-name>
            <valid-connection-checker-class-name>
                com.mysql.jdbc.integration.jboss.MysqlValidConnectionChecker
            </valid-connection-checker-class-name>
            <metadata>
                <type-mapping>mySQL</type-mapping>
            </metadata>
        </xa-datasource>
    
        <!--
            non-transactional datasource for database structure patches, Quartz, etc.
            As per convention, non-transactional datasources have the same name like
            transactional but use the suffix "NoTX"
        -->
        <no-tx-datasource>
            <jndi-name>jdbc/flexiveDivision1NoTX</jndi-name>
            <driver-class>com.mysql.jdbc.Driver</driver-class>
            <!-- Note: "&amp;" has to be used instead of "&" for parameters -->
            <connection-url>jdbc:mysql://localhost:3306/flexive?useUnicode=true&amp;characterEncoding=utf8&amp;characterResultSets=utf8</connection-url>
            <user-name>root</user-name>
            <password>a</password>
    
            <!--pooling parameters-->
            <min-pool-size>5</min-pool-size>
            <max-pool-size>20</max-pool-size>
            <blocking-timeout-millis>5000</blocking-timeout-millis>
            <idle-timeout-minutes>15</idle-timeout-minutes>
    
            <!-- If you supply the usr/pw from a JAAS login module -->
            <security-domain/>
    
            <exception-sorter-class-name>
                com.mysql.jdbc.integration.jboss.ExtendedMysqlExceptionSorter
            </exception-sorter-class-name>
            <valid-connection-checker-class-name>
                com.mysql.jdbc.integration.jboss.MysqlValidConnectionChecker
            </valid-connection-checker-class-name>
            <metadata>
                <type-mapping>mySQL</type-mapping>
            </metadata>
        </no-tx-datasource>
    
        <xa-datasource>
            <jndi-name>jdbc/flexiveConfiguration</jndi-name>
            <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
            <!-- Note: "&amp;" has to be used instead of "&" for parameters -->
            <xa-datasource-property name="URL">jdbc:mysql://localhost:3306/flexiveConfiguration?useUnicode=true&amp;characterEncoding=utf8&amp;characterResultSets=utf8</xa-datasource-property>
            <user-name>root</user-name>
            <password>a</password>
    
            <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
            <no-tx-separate-pools/>
            <!-- This disables transaction interleaving (which BTW, most DB vendors don't support) -->
            <track-connection-by-tx/>
            <isSameRM-override-value>false</isSameRM-override-value>
    
            <!--pooling parameters-->
            <min-pool-size>5</min-pool-size>
            <max-pool-size>20</max-pool-size>
            <blocking-timeout-millis>5000</blocking-timeout-millis>
            <idle-timeout-minutes>15</idle-timeout-minutes>
    
            <!-- If you supply the usr/pw from a JAAS login module -->
            <security-domain/>
    
            <exception-sorter-class-name>
                com.mysql.jdbc.integration.jboss.ExtendedMysqlExceptionSorter
            </exception-sorter-class-name>
            <valid-connection-checker-class-name>
                com.mysql.jdbc.integration.jboss.MysqlValidConnectionChecker
            </valid-connection-checker-class-name>
            <metadata>
                <type-mapping>mySQL</type-mapping>
            </metadata>
        </xa-datasource>
    
    </datasources> 
    
                                

  • Extend ${jboss.home}/server/default/conf/jboss-log4j.xml to configure logging:

        
    <!-- Limit flexive -->
    <category name="com.flexive">
        <priority value="INFO"/>
    </category>
    
    <!-- Limit ajax4jsf -->
    <category name="org.ajax4jsf">
        <priority value="WARN"/>
    </category>
    

  • Optional if you need JAAS support: Extend ${jboss.home}/server/default/conf/login-config.xml with the following entry:

        
    <application-policy name = "FxLogin">
         <authentication>
           <login-module code="com.flexive.core.security.FxDefaultLogin" flag="required"></login-module>
         </authentication>
    </application-policy>
    

  • Optional step: To use an external service deployer for JBoss Cache, create the cache service file 99_JBossCacheJNDI42-service.xml in ${jboss.home}/server/default/deploy/ or simply copy it from the [fleXive] source tree, if available:

                                <?xml version="1.0" encoding="UTF-8"?>
    <server>
    
       <loader-repository>com.flexive:archive=flexive.ear
       </loader-repository>
    
       <!-- ========================================================== -->
       <!-- Clustered SFSB cache config for use with JBoss Cache 1.4.x --> 
       <!-- ========================================================== -->
       <mbean code="org.jboss.cache.jmx.CacheJmxWrapper"
              name="jboss.cache:service=JNDITreeCache">
          <!--<depends>jboss:service=Naming</depends>-->
          <!--<depends>jboss:service=TransactionManager</depends>-->
    
          <attribute name="TransactionManagerLookupClass">org.jboss.cache.transaction.GenericTransactionManagerLookup</attribute>
            
           <!--
                   Node locking scheme :
                                       PESSIMISTIC (default)
                                       OPTIMISTIC
           -->
          <attribute name="NodeLockingScheme">PESSIMISTIC</attribute>
           
          <attribute name="ClusterName">[fleXive]-Cache-JNDI</attribute>
          
          <!--
                  Node locking level : SERIALIZABLE
                                       REPEATABLE_READ (default)
                                       READ_COMMITTED
                                       READ_UNCOMMITTED
                                       NONE
          -->
          <attribute name="IsolationLevel">READ_COMMITTED</attribute>
    
          <!--     Valid modes are LOCAL
                                   REPL_ASYNC
                                   REPL_SYNC
          -->
          <attribute name="CacheMode">REPL_ASYNC</attribute>
    
    	  <!-- We want to activate/inactivate regions as beans are deployed -->
          <attribute name="UseRegionBasedMarshalling">true</attribute>
          <!-- Must match the value of "useRegionBasedMarshalling" -->
          <attribute name="InactiveOnStartup">true</attribute>
    
    	  <!-- 
    	       JGroups protocol stack config in XML format.
    		   If your CacheMode is set to REPL_SYNC we recommend you comment
               out the FC (flow control) protocol
    			 
               On Windows machines, because of the media sense feature
               being broken with multicast (even after disabling media sense)
               set the UDP.loopback attribute to true
    	  -->     
          <attribute name="ClusterConfig">
             <config>
                <UDP mcast_addr="${flexive.cluster.udpGroup:229.1.2.5}"
                 mcast_port="${jboss.ejb3sfsbpartition.mcast_port:45557}"
                 tos="8"
                 ucast_recv_buf_size="20000000"
                 ucast_send_buf_size="640000"
                 mcast_recv_buf_size="25000000"
                 mcast_send_buf_size="640000"
                 loopback="false"
                 discard_incompatible_packets="true"
                 enable_bundling="false"
                 max_bundle_size="64000"
                 max_bundle_timeout="30"
                 use_incoming_packet_handler="true"
                 use_outgoing_packet_handler="false"
                 ip_ttl="${jgroups.udp.ip_ttl:2}"
                 down_thread="false" up_thread="false"/>
              <PING timeout="2000"
                 down_thread="false" up_thread="false" num_initial_members="3"/>
              <MERGE2 max_interval="100000"
                 down_thread="false" up_thread="false" min_interval="20000"/>
              <FD_SOCK down_thread="false" up_thread="false"/>
              <FD timeout="10000" max_tries="5" down_thread="false" up_thread="false" shun="true"/>
              <VERIFY_SUSPECT timeout="1500" down_thread="false" up_thread="false"/>
              <pbcast.NAKACK max_xmit_size="60000"
                       use_mcast_xmit="false" gc_lag="0"
                       retransmit_timeout="300,600,1200,2400,4800"
                       down_thread="false" up_thread="false"
                       discard_delivered_msgs="true"/>
              <UNICAST timeout="300,600,1200,2400,3600"
                 down_thread="false" up_thread="false"/>
              <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000"
                       down_thread="false" up_thread="false"
                       max_bytes="400000"/>
              <pbcast.GMS print_local_addr="true" join_timeout="3000"
                       down_thread="false" up_thread="false"
                       join_retry_timeout="2000" shun="true"
                       view_bundling="true"
                       view_ack_collection_timeout="5000"/>
              <FC max_credits="2000000" down_thread="false" up_thread="false"
                  min_threshold="0.10"/>
              <FRAG2 frag_size="60000" down_thread="false" up_thread="false"/>
              <pbcast.STATE_TRANSFER down_thread="false" up_thread="false" use_flush="false"/>
            </config>
          </attribute>
    
          <!--    The max amount of time (in milliseconds) we wait until the
                initial state (ie. the contents of the cache) are retrieved from
                existing members.
          -->
          <attribute name="InitialStateRetrievalTimeout">17500</attribute>
    
          <!--    Number of milliseconds to wait until all responses for a
                  synchronous call have been received.
          -->
          <attribute name="SyncReplTimeout">17500</attribute>
    
          <!--  Max number of milliseconds to wait for a lock acquisition -->
          <attribute name="LockAcquisitionTimeout">15000</attribute>
    
          <!--  Specific eviction policy configurations. -->
          <attribute name="EvictionPolicyConfig">
             <config>
                <attribute name="policyClass">org.jboss.cache.eviction.LRUPolicy</attribute>
                <attribute name="wakeUpIntervalSeconds">5</attribute>
                <name>flexiveMain</name>
                <!-- So default region would never timeout -->
                <region name="/_default_">
                   <attribute name="maxNodes">0</attribute>
                   <attribute name="timeToLiveSeconds">0</attribute>
                </region>
                <!-- cache region for contents -->
                <region name="/Division1/FxContent">
                    <attribute name="maxNodes">1000</attribute>
                    <attribute name="timeToLiveSeconds">1000</attribute>
                </region>
                 <!-- cache region for user configuration -->
                 <region name="/Division1/userConfig">
                     <attribute name="maxNodes">10000</attribute>
                     <attribute name="timeToLiveSeconds">1000</attribute>
                 </region>
             </config>
          </attribute>
       </mbean>
    </server>
    
                            

    If you want to use the external cache deplyoment you have to apply another modification: Due to classloading issues ([fleXive] uses JBoss Cache 2.x, while JBoss 4.2 uses JBoss Cache 1.x) you need to modify the deployment scanner in ${jboss.home}/server/default/conf/jboss-service.xml: replace the entry

                                <attribute name="URLComparator">org.jboss.deployment.DeploymentSorter</attribute>

    with

                                <attribute name="URLComparator">org.jboss.deployment.scanner.AlphaNumericDeploymentSorter</attribute>

    This ensures that the cache service is started after flexive.ear is deployed and thus can use its cache implementation classes (this deployment scanner allows to influence the deployment order with a numeric prefix, otherwise it's the same as the default one).

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

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 datasource configuration

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

    <!-- Configure the global configuration datasource -->
    
    <jdbc-connection-pool
        name="flexiveConfiguration"
        datasource-classname="com.mysql.jdbc.jdbc2.optional.MysqlXADataSource"
        res-type="javax.sql.XADataSource">
        <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">
        <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">
        <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>
            

While Glassfish is running, execute ${glassfish.home}/bin/asadmin add-resources /path/to/flexive-ds.xml to create the connection pools and JDBC resources. 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 ResourcesJDBC.

This procedure is for those building [fleXive] from the source code.

  • Copy the build.properties.sample file located in the root directory of the [fleXive] source code to build.properties.
        
    jboss.home=/path/to/jboss
    
    # path to deploy the ear
    deploy.ear.path=${jboss.home}/server/all/deploy
    
    # path to deploy needed runtime libs like emma.jar
    deploy.lib.path=${jboss.home}/server/all/lib
    
    # path to the embedded jboss ejb3 container neededfor unit testing
    jboss.embedded.path=${jboss.home}/jboss-embeddable/
    
    # (...)
    
  • Execute ant db.update before ant all in the root directory of the [fleXive] source code, where the build.xml file resides. This will recreate all configured databases and destroy existing data.
  • To deploy the ear execute ant deploy

    Don't forget to set your ${jboss.home} variable in the build.properties file properly!

    • Note: to successfully compile [fleXive] JAVA 1.6 and Apache ANT 1.7 is needed
    • Be also sure to set the JDK_HOME and JAVA_HOME variables accordingly as explained in section Prerequisites.

In this chapter we will get hands-on and create a few demo applications with [fleXive]. These applications are part of the binary and source distributions, but you can also download them as separate projects:

  • helloworld is our canonical hello-world application,
  • tutorial01-documentstore show some of the document-handling capabilities in [fleXive],
  • products shows a localized frontend for a product database realized in [fleXive], and
  • announcement-submission shows a basic security setup of a publishing application with two usergroups ("editors" and "users").

To run any of these, unzip them to a local directory. Unzip the [fleXive] distribution from the download page in the same directory, remove the precompiled examples from flexive-dist/applications, and execute ant in the example directory. You can then deploy the dist/[example-name].ear file to your application server. For example (using Linux):

$ unzip flexive-dist.zip
$ unzip example-helloworld.zip
$ ls
flexive-dist helloworld

$ cd helloworld
$ ant
$ ls dist
helloworld.ear  helloworld-shared.jar  helloworld.war

Before setting out on your own, you might also want to read Chapter 4, Writing [fleXive] applications , which also explains how to use Apache Maven as your build tool.

Our first [fleXive] application implements a very simple blogging system with an input mask and a view for the submitted entries. We assume you have a flexive installation up and running on your local or on a remote machine. If not, follow the instructions in Chapter 2, Installing [fleXive] . The complete source code can be found here or in the subversion repository under src/examples/helloworld.

First we create a new [fleXive] project: go to the directory where you unpacked the distribution, and execute ant project.create. You will be prompted for the name of the new project. Enter helloworld and confirm your input. If all went well, the output should look like the following:

/tmp/flexive-dist$ ant project.create
Buildfile: build.xml

check:

project.create:
    [input] Name of the project you want to create:
helloworld
  [flexive]
  [flexive] Please confirm your input:
  [flexive] Project name:        helloworld
  [flexive] Base directory:      ../helloworld
  [flexive]
    [input] Are these settings correct? ([y], n)
y
    [mkdir] Created dir: /tmp/helloworld
     [copy] Copying 13 files to /tmp/helloworld
     [copy] Copied 29 empty directories to 6 empty directories under /tmp/helloworld
     [copy] Copying 1 file to /tmp/helloworld
     [copy] Copying 1 file to /tmp/helloworld
     [echo] Project helloworld created successfully. The project root directory is
     [echo] ../helloworld

BUILD SUCCESSFUL

The new project is created in the parent directory of the distribution, i.e. in ../helloworld, and looks like this:

flexive-dist
|-- ...

helloworld
|-- build.xml
|-- database.properties
|-- lib
|-- resources
|   |-- META-INF
|   |   |-- faces-config.xml
|   |   `-- web.xml
|   |-- messages
|   |-- scripts
|   |   |-- library
|   |   |-- runonce
|   |   `-- startup
|   `-- templates
|-- src
|   `-- java
|       |-- ejb
|       |   `-- ...
|       |-- shared
|       |   `-- ...
|       `-- war
|           `-- ...
`-- web
    `-- index.xhtml

For the web interface of the application we use JSF 1.2, using Facelets for creating the JSF views (i.e. we use plain XHTML templates instead of JSP). [fleXive] includes components for rendering and editing [fleXive] contents in JSF applications, although you could also use other web framework like Struts or Tapestry - you'd just miss the convenient UI components that allow a rapid creation of web applications based on [fleXive].

If you are not familiar with JSF tag libraries please refer to the Tag Library Documentation or try the JSF section of the Java EE 5 Tutorial.

The main page renders all available blog entries and shows a link to a form for creating new entries. Facelets' <ui:repeat/> tag is used to iterate over the rows of the datamodel returned by the JSF bean we created in the previous section. A row of the datamodel provides indexed access to the columns selected in the search query of the previous section. In this case, #{columns[0]} would be the content primary key (@pk), #{columns[1]} returns the entry title, and so on. The source for this file can be found under web/index.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:fx="http://www.flexive.com/jsf/core">
<head>
    <fx:includes/>
</head>

<body>

<h:outputLink value="create.xhtml">Create a new entry</h:outputLink>

<!-- Render available blog postings, as returned by helloWorldBean.blogEntries -->

<!-- The Facelets ui:repeat tag is used to iterate over arrays, lists and JSF datamodels -->
<ui:repeat value="#{helloWorldBean.blogEntries}" var="column">
    <h3>
        <!-- Entry title. Access the value of each column through the expression language
         and the column index -->
        #{column[1]}
    </h3>
        <pre>#{column[2]} <!-- Entry text -->

            <i>#{column[3]}</i> <!-- Creation date -->
        </pre>
</ui:repeat>

<p><h:outputLink
        onclick="window.open('http://wiki.flexive.org/confluence/display/FX/Listing+blog+entries', '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>
            

The input form for creating new postings is placed in web/create.xhtml and uses the <fx:content/> and <fx:value/> components provided by [fleXive] to create a simple input form for [fleXive] contents. All you need to provide is the name of the type you want to use as template (blogEntry) and the references to the properties to be rendered (entryTitle, entryText). Finally, a JSF command link is used to render a button for saving the entered data. The save command is executed by a [fleXive] system bean, fxContentViewBean.

                <!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>
    <title>Flexive Helloworld Application</title>
    <fx:includes/>
</head>

<body>

<h:form>
    <!-- Display all JSF messages -->
    <h:messages/>

    <p><h:outputLink value="index.xhtml">Back to blog</h:outputLink></p>

    <!-- The fx:content tag references our type "Blog Entry" -->
    <fx:content typeName="blogEntry" var="entry">

        <!-- This renders an html input field for the type's property "Entry Title" -->
        <fx:value property="entryTitle"/>

        <!-- This renders an html input field for the type's property "Entry Text" -->
        <fx:value property="entryText"/>

        <!-- Save content using the FxContentViewBean, pass the content instance
             stored in component_content via f:setPropertyActionListener -->
        <h:commandLink action="#{fxContentViewBean.save}">
            <f:setPropertyActionListener target="#{fxContentViewBean.content}" value="#{entry_content}"/>
            Publish
        </h:commandLink>

    </fx:content>
</h:form>

<p><h:outputLink
        onclick="window.open('http://wiki.flexive.org/confluence/display/FX/Creating+a+blog+entry', '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>
            

To compile and deploy the framework and the example application simply run ant in the project directory (helloworld). If the compilation was successful, you find your application packaged under dist/helloworld.ear. You can then deploy this EAR to your application server, assuming that you followed the installation instructions. If you already have a [fleXive] EAR deployed in this instance, be sure to undeploy it before you deploy helloworld.ear.

If you need to setup or reset the database schema, update your database connection settings in hello-world/database.properties or flexive-dist/database.properties and run ant db.create in the corresponding directory.

After deploying the application, point your browser to http://localhost:8080/flexive/adm/ to open the backend administration application (default credentials: supervisor/supervisor), or http://localhost:8080/helloworld/ to open the application. Congratulations! You should see a link to the input mask.

Now that you are familiar with some basic concepts of [fleXive], we are ready to explore more features. The first tutorial application introduces

  • binary support in [fleXive] contents,

  • combined create/edit forms, as well as

  • a more sophisticated way of rendering results, like automatic preview images of contents.

Our task for this tutorial is to create a centralized document store that allows us to store documents, images or videos and provides a web-based user interface for it. In the first tutorial we will implement the basic functionality, and then further refine and extend the features in following tutorials. Figure 3.1, “The document store application, version 1” shows the end result of the first tutorial, with the help of some stylesheets that can be found in the tutorial source tree.


First we create new project called tutorial01-documentstore. Use your local installation of the [fleXive] distribution as described in the section called “Your first [fleXive] application” to create a new project. The complete source code can be found here. We start by defining our data model used for storing documents. We assign the standard caption property /caption for document captions, and add a Binary property. We create the type in the run-once script resources/scripts/runonce/tutorial001.groovy:

                    /**
 * Initialization script for the tutorial01 application.
 *
 * @author Daniel Lichtenberger (daniel.lichtenberger@flexive.com), UCS - unique computing solutions gmbh (http://www.ucs.at)
 * @version $Rev: 461 $
 */

import com.flexive.shared.scripting.groovy.*
import com.flexive.shared.value.*
import com.flexive.shared.structure.*

new GroovyTypeBuilder().document01(
        description: new FxString(true, "Tutorial document 01"),
        usePermissions: false)
{
    // assign the root caption under /caption
    caption(assignment: "ROOT/CAPTION")

    // store the mandatory binary under /file
    file(dataType: FxDataType.Binary,
         multiplicity: FxMultiplicity.MULT_1_1,
         description: new FxString(true, "File"))
}

                

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.

Similar to the helloworld example application, we iterate over the rows of the result data model using <ui:repeat>. But this time, we render the result using the <fx:resultValue> tag, which essentially renders read-only <fx:valueInput> components for more sophisticated output formatting. For the document browser, we select four columns in our content query:

  1. @pk,

  2. document01/file,

  3. caption, and

  4. created_at.

When we pass a value of the second column (document01/file) to the <fx:resultValue> component, it actually renders an inline image that displays a preview of the uploaded file. For image data types, this is a thumbnail, for other types like documents or presentations, it is an icon corresponding to the document type. So to render a list of thumbnail preview images, we write the following:

<ui:repeat var="row" value="#{tutorialBean.documents}">
    <fx:resultValue value="#{row[1]}"/>
</ui:repeat>

We can still write the result values as literal JSF-EL expressions when necessary, so for example to add the caption after each image it would be sufficient to write #{row[2]}. However, the <fx:resultValue> tag adds extra functionality like date formatting or support for inline HTML properties (otherwise HTML contained in an FxHTML would be escaped by Facelets), so it's generally a good idea to use <fx:resultValue> for any result value rendered in the response.

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>
                

The upload form allows both to create new document objects by uploading files and editing existing ones. It works exactly as the form for entering new blog posts in the helloworld tutorial, except that we specify an explicit content instance that may be set from an edit link on the overview page:

<fx:content typeName="document01"
                        content="#{fxContentViewBean.content}"
                        var="document">
                    

When this page is opened through the "Upload" link on the front page (or by entering the URL to /upload.xhtml in the browser location bar), #{fxContentViewBean.content} evaluates to null and a new content instance of type document01 will be initialized. Otherwise, the content instance from retrieved from the fxContentViewBean will be edited. A call to fxContentViewBean.save creates or updates the content instance in the database.

The upload form renders two new input components:

  • a file upload form, and

  • a multilanguage input for the caption property.

For file uploads to work, you need to set the enctype attribute of the HTML form to multipart/form-data:

<h:form enctype="multipart/form-data">

We then create the upload page under web/upload.xhtml and add a basic content editor for creating new documents. The input component supports binary properties, but you have to set the form encoding to multipart/form-data.

                        <!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>

<h:messages globalOnly="true"/>

<h:form enctype="multipart/form-data">

    <ul id="mainmenu">
        <li>
            <h:outputLink value="index.xhtml">Return to overview</h:outputLink>
        </li>
    </ul>


    <!--
         Create a new content of type document01 or edit an existing content instance if set in fxContentViewBean.
    -->
    <fx:content typeName="document01" content="#{fxContentViewBean.content}" var="document">

        <fx:fieldSet legend="Document Upload">
            <!-- Render the input form -->
            <fx:value property="file"/>
            <fx:value property="caption"/>

            <!-- Render the submit button -->
            <fx:formRow>
                <h:commandButton action="#{fxContentViewBean.save}" value="Save">
                    <f:setPropertyActionListener target="#{fxContentViewBean.content}" value="#{document_content}"/>
                    <f:setPropertyActionListener target="#{fxContentViewBean.successMessage}"
                                                 value="Successfully saved the document."/>
                </h:commandButton>
            </fx:formRow>

        </fx:fieldSet>

    </fx:content>

</h:form>

<p><h:outputLink
        onclick="window.open('http://wiki.flexive.org/confluence/display/FX/Uploading+documents', '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>
                    

To compile and deploy the framework and the example application simply run ant in the project directory (tutorial01-documentstore). If the compilation was successful, you find your application packaged under dist/tutorial01-documentstore.ear. You can then deploy this EAR to your application server, assuming that you followed the installation instructions. If you already have a [fleXive] EAR deployed in this instance, be sure to undeploy it before you deploy tutorial01-documentstore.ear.

If you need to setup or reset the database schema, update your database connection settings in tutorial01-documentstore/database.properties or flexive-dist/database.properties and run ant db.create in the corresponding directory.

After deploying the application, point your browser to http://localhost:8080/flexive/adm/ to open the backend administration application (default credentials: supervisor/supervisor), or http://localhost:8080/tutorial01-documentstore/ to open the application.

There are two convenient ways to start a new [fleXive] project:

  1. to use the [fleXive] distribution and utilize its Apache Ant build infrastructure, or

  2. to use Apache Maven and add [fleXive] to your project dependencies.

While 1) offers you out-of-the-box support for all [fleXive] features such as run-once scripts, plugins, weblet resources and so on, 2) is more modular and allows you to use [fleXive] just as any other library. Of course you can also use [fleXive] in your own enterprise application by adding the libraries.

The easiest way to get started with [fleXive] is to grab a distribution package from the download page, unzip it to a local development directory, and create a new project from scratch. In this chapter we will concentrate on creating new [fleXive] applications.

Looking at your local [fleXive] distribution directory, you will find the following directory layout:

.
|-- META-INF/
|-- build.xml
|-- applications/
|-- extlib/
|-- lib/
|-- templates/

build.xml

Contains the build file for creating new projects and components. To get started, simply execute ant in your flexive-dist/ directory.

applications

Contains all [fleXive] applications that should be included in the EAR file. The standard distribution includes the backend administration application in this directory. To remove an application from the EAR, simply remove it from this directory and rebuild the EAR file.

lib

Contains all [fleXive] libraries packaged as JAR files.

extlib

Contains all third-party libraries required for compiling and running [fleXive] applications. Note that not all libraries in this directory will be packaged into the final application archive, for example the JSF API package is only required for compiling JSF applications.

templates

Contains project and component templates used by the build system.

META-INF

Currently this directory only holds a template application descriptor for [fleXive] applications.

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

For running the application you need a working environment including MySQL as described in the installation chapter.

To get started with your first [fleXive] application, open a command shell and change to the directory containing the [fleXive] distribution. Type ant. You should be greeted by the welcome page of the [fleXive] build system:

Buildfile: build.xml

info:
  [flexive]
  [flexive] Welcome to the flexive build tool. Feel free to use the following build targets:
  [flexive]
  [flexive] project.create
  [flexive]     Creates a new flexive project directory.
  [flexive]
  [flexive] component.create
  [flexive]     Creates a new flexive UI component directory.
  [flexive]
  [flexive] db.create
  [flexive]     Create or reset the database schema of a flexive division.
  [flexive]     Warning: if the schema already exists, it will be dropped (i.e. you will lose all data
  [flexive]     stored in the schema).
  [flexive]
  [flexive] db.config.create
  [flexive]     Create or reset the global flexive configuration schema.
  [flexive]
  [flexive] ear
  [flexive]     Create a flexive.ear distribution including any flexive application stored in
  [flexive]     flexive-dist/applications.
  [flexive]
  [flexive] glassfish.libs
  [flexive]     Copies libraries needed for Glassfish compatibility to a directory
  [flexive]
    [input] Please enter a target name, or quit to exit:

Let's create a new project. Type project.create and hit return. You will be asked for a project name. This name will be used as the root directory name for the project, so be careful to include only characters that may appear in filenames and URLs. For a start, enter flexive-test.

[fleXive] will create the project folder in the same directory where the [fleXive] distribution is stored, i.e. in the current parent directory. The major reason for this is that the project references the distribution directory, i.e. it includes all the libraries from the distribution directory and does not use its own copies. Thus new [fleXive] projects use little disk space, and you need only one [fleXive] distribution for all your projects.

After confirming your selection, the root directory layout for flexive-test will be created. Your screen should look approximately like this:

    [input] Please enter a target name, or quit to exit:
project.create

check:

project.create:
    [input] Name of the project you want to create:
flexive-test
  [flexive]
  [flexive] Please confirm your input:
  [flexive] Project name:        flexive-test
  [flexive] Base directory:      ../flexive-test
  [flexive]
    [input] Are these settings correct? ([y], n)
y
    [mkdir] Created dir: /home/daniel/dev/idea-workspace/flexive/flexive-test
     [copy] Copying 4 files to /home/daniel/dev/idea-workspace/flexive/flexive-test
     [copy] Copied 14 empty directories to 9 empty directories under /home/daniel/dev/idea-workspace/flexive/flexive-test
     [copy] Copying 1 file to /home/daniel/dev/idea-workspace/flexive/flexive-test
     [copy] Copying 1 file to /home/daniel/dev/idea-workspace/flexive/flexive-test
     [echo] Project flexive-test created successfully. The project root directory is
     [echo] ../flexive-test

BUILD SUCCESSFUL

When the build tool has finished successfully, go to the newly created directory, e.g. cd ../flexive-test. The directory structure contains a blank project structure, which looks like the following:

.
|-- build.xml
|-- lib
|-- resources
|   |-- META-INF
|   |   |-- faces-config.xml
|   |   |-- template.taglib.xml.sample
|   |   `-- web.xml
|   |-- messages
|   |-- scripts
|   |   |-- library
|   |   |-- runonce
|   |   `-- startup
|   `-- templates
|-- src
|   `-- java
|       |-- ejb
|       |-- shared
|       `-- war
`-- web
    `-- index.xhtml

Before examining the directory structure, let's do a quick test if the the environment is working. Type ant. The build should complete successfully, leaving you with some artifacts in the dist/ subdirectory:

  • flexive-test.ear,

  • flexive-test-shared.jar, and

  • flexive-test.war.

To deploy the application, first you need to setup the database schemas. Type ant db.create db.config.create and when prompted for the database schema use the default name, flexive. When the command completed successfully, your can deploy flexive-test.ear and have a working (albeit empty) [fleXive] application, including the backend administration application.

The project root directory contains a build file, build.xml, that can be customized for the project. By default, it builds JAR files for all layers, including an EAR archive. The major subdirectories are:

src/java

contains the Java sources of the project. They are split up by layer, i.e. there are three distinct source trees for the EJB, web, and shared classes. This is especially useful for IDEs with support for multiple project modules, where you can also specify wanted (and forbidden) relationships between the layers.

web

contains the documents for the web application (if any).

lib

contains additional libraries and components used by the project.

resources

is the root folder for various project resources:

resources/scripts

contains the run-once, startup and library scripts of the application,

resources/messages

contains the application's localized message resources that can be accessed with the fxMessageBean,

resources/META-INF

contains the application's configuration files, mostly for the web layer,

resources/templates

is the standard folder for Facelets templates. You can choose any folder of course if you like, but then you'd have to modify the build script.

Your [fleXive] project comes with basic project files for the Eclipse and IntelliJ IDEA Java IDEs.

If this is your first Eclipse project with [fleXive], first you have to define a new user library that includes the JAR files of your [fleXive] distribution. We also could include these files in the individual project classpath, but this way is much cleaner and easier to work with especially for multiple projects.

  1. Please go to WindowPreferencesJavaBuild PathUser Libraries.

  2. Click New... and enter flexive for the library name. Press OK.

  3. Select the created library entry, and press the Add JARs... button.

  4. Go to your [fleXive] distribution directory, and select all JAR files in the lib/ folder (you can use shift-select here).

  5. Repeat the last two steps and add all JAR files of the extlib/ folder and the flexive-plugin-jsf-core.jar from the applications/ folder to the user library.

  6. In the User Libraries page, click OK. You have now defined a global flexive library that includes all required JAR files for a [fleXive] application. Note that this is only available within the IDE, the actual build files do not use the IDE-specific library definitions.

Assuming that both your flexive-dist directory and the newly created project reside in your current Eclipse workspace directory, you can add the project following these steps:

  1. Open FileImport...+GeneralExisting Projects into Workspace

  2. Select the project root directory.

  3. Press Finish. Eclipse should now open the project in the workspace. To build the project EAR file using Ant, execute ProjectBuild all.

    To check if the project and library has been loaded correctly, try to open the EJBExampleBean class using NavigationOpen Type... ( Shift+Ctrl+T ) Eclipse should display the source code without errors.

We start with creating a new project for the flexive-test application directory.

  1. Open FileNew Project...

  2. Select Create project from scratch and press Next.

  3. Choose your [fleXive] project directory in Project file location.

  4. Click Next.

  5. Uncheck Create module and click Finish.

Let IDEA open the project. Next we add the template module file in the IDEA project settings dialog:

  1. Add a new module by clicking on the "+" button at the top of the screen.

  2. Choose Import existing module and select the IDEA module file (flexive-test.iml) in your project directory.

  3. Press Finish.

If this is your first IntelliJ IDEA project with [fleXive], please perform the following setup steps. Similar to Eclipse, we use a shared library definition to include [fleXive] in the project classpath.

  1. Open FileSettings

  2. Click on Project settings.

  3. On the left-hand-side, click on Platform settingsGlobal Libraries

  4. Add a new library by clicking on the "+" button at the top of the screen. Enter flexive-dist as the library name.

  5. Select your project module in the next screen and press OK.

  6. In the library overview screen, select the flexive-dist library and add the flexive-dist/applications, flexive-dist/lib and flexive-dist/extlib directories using the Attach JAR directories button.

Now you should have all [fleXive] classes available in your project. You can test this by opening the example EJB ( EJBExampleBean) using Go ToClass... ( Ctrl+N ) IDEA should not display any errors like missing classes.

If you created a new [fleXive] application with the tools of this chapter, it will include a buildfile for Apache Ant that compiles and packages the application into JAR and EAR files as described in the previous section. It uses a shared generic build file from the flexive-dist directory that is customized by setting a few Ant properties:

fxProject

The project name, in our example flexive-test.

flexive.dist.dir

The [fleXive] distribution directory. By default this is a relative location. Keep this and do not alter the directory name if you want to keep the build environment independent from the actual workspace location.

[basename].shared.disabled , [basename].ejb.disabled , [basename].war.disabled , [basename].ear.disabled

If any of these properties is set, the corresponding archive file will not be generated. [basename] is the project name as set in the fxProject property, in our example application we would skip the EAR file generation using <property name="flexive-test.ear.disabled" value="1"/>.

The resulting JAR and EAR files will be stored in the dist/ directory of the project. If you deploy the EAR file into your application server, please make sure that no other [fleXive] EAR is deployed to prevent conflicts.

The default Apache Ant target builds the entire application, including an EAR file that can be deployed into your application server. Additional tasks are provided for setting up the database schemas.

package (default)

Build all archives, except disabled ones as described in the previous section.

help

Display a short help message and offer documentation of the most relevant tasks.

db.create

Create or reset a [fleXive] division database schema. By default, the first division uses the schema flexive.

db.config.create

Create or reset the global [fleXive] configuration schema, flexiveConfig.

Apache Maven is a build tool like Apache Ant, but with a completely different approach to managing software builds: where Apache Ant is like a procedural programming language for describing how to build your system, Apache Maven is more of a fully-fledged assembly line for building, packaging, testing, and running software projects.

The Maven repository at http://repo.flexive.org/maven2/ contains all [fleXive] libraries with correct dependencies set up. To use it in your Maven project, add the following repository to your pom.xml:

<repository>
    <id>maven.flexive.org</id>
    <name>Flexive repo</name>
    <url>http://repo.flexive.org/maven2</url>
    <layout>default</layout>
</repository>

The repository contains all released versions, including snapshots for all active branches that are updated from our internal continuous integration servers. Use these -SNAPSHOT revisions to use the latest features and bugfixes, but don't use them in a final product!

To resolve all dependencies of [fleXive], you also need to add the following repositories from java.net and JBoss:

<repository>
    <id>maven2-repository.dev.java.net</id>
    <name>Java.net Repository for Maven</name>
    <url>http://download.java.net/maven/2/</url>
    <layout>default</layout>
    <snapshots>
        <updatePolicy>never</updatePolicy>
    </snapshots>
</repository>

<repository>
    <id>maven2-jboss</id>
    <name>JBoss Maven Repository</name>
    <url>http://repository.jboss.org/maven2</url>
    <layout>default</layout>
    <snapshots>
        <updatePolicy>never</updatePolicy>
    </snapshots>
</repository>

<repository>
    <id>maven-dev-repository.dev.java.net</id>
    <name>Java.net Dev Repository for Maven</name>
    <url>https://maven-repository.dev.java.net/repository/</url>
    <layout>legacy</layout>
    <snapshots>
        <updatePolicy>never</updatePolicy>
    </snapshots>
</repository>

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.

The archetypes are (as the rest of the Maven modules) still under development, so please report rough edges or missing features in our issue tracker.

The archetype flexive-archetype-ear creates a multi-module enterprise application, which will be deployed as an EAR. It also allows easy integration testing with OpenEJB and offers a standalone webserver using Jetty and H2.

To get started, create a new project using the following command:

mvn archetype:generate -DarchetypeGroupId=com.flexive -DarchetypeArtifactId=flexive-archetype-ear -DarchetypeVersion=1.0-SNAPSHOT -DarchetypeRepository=http://repo.flexive.org/maven2/ -DgroupId=mygroup -DartifactId=hello-flexive -Dversion=0.1-SNAPSHOT

This will create a new project called "hello-flexive" in the current directory. The [fleXive] version to be used can be specified in the main module's pom.xml file. By default, it is set to the current release required for all features (currently this is 3.1-SNAPSHOT). For a list of available versions, please look at the Maven repository (e.g. here).

Maven snapshot versions

The snapshot versions in our Maven repository ( 3.0-SNAPSHOT and 3.1-SNAPSHOT) are updated automatically from our internal Continuous Integration server (Hudson) with the latest stable build of the corresponding branch. A build is considered "stable" in this context if no testcase fails. The snapshot versions are a convenient way of getting and testing the latest features, however these builds are not tested manually and may cause all kinds of havoc including data loss. If possible, it is recommended to use stable versions.

The following commands (issued in the project directory) will walk you through the most important features:

mvn package

Compile and package the application. The resulting EAR file can be deployed in any supported application server (for setup instructions, consult Chapter 2, Installing [fleXive] ).

mvn install

Compile, package and install the application. If executed for the first time, the H2 database schemas will also be created in the database/h2 subdirectory.

mvn install -Pflexive-db-setup-h2 (since 3.1)

Compile, package and install the application. Manually activate the profile flexive-db-setup-h2 to reset the H2 database in the database/h2 subdirectory.

cd war , mvn jetty:run (since 3.1)

Start an instance of the Jetty WebServer to deploy our application (including the backend administration application) and OpenEJB. The available applications can be browsed at http://localhost:8080.

Additional information on working with the Maven archetypes can be found in the following blog entries:

Warning: version 3.0.x and embedded containers

Please note that some features are dependent on the [fleXive] version: H2/OpenEJB/Jetty support is only available in 3.1 or later. In order to build your project with [fleXive] 3.0.x, you have to disable the database and consoleapp modules in your root pom.xml. Then you can package an EAR file using the mvn package command.

While you can browse all artifacts at http://repo.flexive.org/maven2/, the following list enumerates those you will most likely end up using in your application.

flexive-ejb

The [fleXive] EJB layer (packaging: ejb). Add this to your EAR module.

<dependency>
    <groupId>com.flexive</groupId>
    <artifactId>flexive-ejb</artifactId>
    <version>3.0.2</version>
    <type>ejb</type>
</dependency>
flexive-shared

The [fleXive] shared classes, including all EJB interfaces. Use this artifact in modules that need to access [fleXive] via EJB, but are not EJBs themselves (e.g. web modules).

<dependency>
    <groupId>com.flexive</groupId>
    <artifactId>flexive-shared</artifactId>
    <version>3.0.2</version>
    <type>jar</type>
</dependency>
flexive-backend

The [fleXive] backend application, including all required libraries and the actual WAR package.

<dependency>
    <groupId>com.flexive</groupId>
    <artifactId>flexive-backend</artifactId>
    <version>3.0.2</version>
    <type>jar</type>
</dependency>
flexive-plugin-jsf-core

The JSF component library (includes flexive-web-shared).

<dependency>
    <groupId>com.flexive</groupId>
    <artifactId>flexive-plugin-jsf-core</artifactId>
    <version>3.0.2</version>
    <type>jar</type>
</dependency>
flexive-web-shared

Shared (framework agnostic) web classes, including authentication filters, servlets for delivering [fleXive] contents.

<dependency>
    <groupId>com.flexive</groupId>
    <artifactId>flexive-web-shared</artifactId>
    <version>3.0.2</version>
    <type>jar</type>
</dependency>

[fleXive] is a comprehensive JavaEE 5 library with an EJB3 interface and a supplementing JSF component library. It is based on current Java enterprise technologies and focuses on flexibility and extensibility. Chapter 6, The [fleXive] core components and Chapter 7, JSF Support explain all key concepts services relevant to users of the [fleXive] framework.

The core of [fleXive] is a collection of EJB3 beans (called engines) that offer services such as content creation and retrieval, search queries and the definition of data structures. The client is usually a web application or another EJB3 that extends or embeds [fleXive] functionality.

The [fleXive] core is based on the following EJB engines:

  • The content engine implements the persistency layer that is used to create, update and delete [fleXive] contents. It is supported by an extensive security layer that offers fine-grained permission controls for all contents managed by [fleXive].

  • The content engine is supplemented by the search engine to search for contents in a SQL-like query language.

  • The structure engine is responsible for creating and editing the dynamic data structures used by the content engine.

  • The tree engine provides a scalable implementation for organizing contents in a hierarchical tree structure.

  • Further engines extend the basic functionality: the scripting engine allows to fire user-defined code at almost any event in the content engine, user management provides access to the user directory, the workflow engine implements workflows for content instances, and the configuration engine stores user preferences and system configuration parameters.

If you remove all eyecandy created by more or less sophisticated user interfaces you will discover the driving force behind [fleXive]: the core layer. It is implemented at the EJB layer and is provided by stateless session beans. These “engines” serve as abstractions to concrete implementations (usually using some form of singleton pattern) for different databases or algorithms used.

The areas covered are structure definition, content manipulation, SQL like queries, organizing contents in trees, scripting, workflow, user management and how security is handled.

Handling users and user information is a basic business of virtually every major software system in use today. At this juncture [fleXive] is no exception. User management in [fleXive] is based on accounts – that is a user and its basic information (name, login name, contact data, e-mail addresss, ...) are stored in accounts.

In the table below you see the listing of all attributes an account in [fleXive] owns.

Table 6.1. Account Attributes
Attribute Description
id, name, login name, e-mail, description, contactDataId Some basic attributes. The Id uniquely identifies the account. The description allows you to characterize the account while the contactDataId identifies the contact data (e.g. postal address, telephon number) linked to this user. Name and login name stand for themselves.
mandatorId The mandator the account belongs to. Note that every account has to be assigned to exactly one mandator.
language Identifies the preferred language for the account. Whenever there are available user interface translations or contents in several languages the system will select to display the ones in the language specified here, if available.
active An account can be set to status inactive. Thus no login is possible while it is not activated again. Note: both flags, active and validated, have to be set to true for the login to work.
validated Flags for admins indicating that the user data was audited and is no fake. Setting this flag to false prevents a login for the corresponding account until the flag is set to true. This setting can be used when auto-creating accounts to force validation of the account data. Note: both flags, active and validated, have to be set to true for the log in to work.
validFrom, validTo The valid from/to dates may be used to define a time periode in which the user may log in.
defaultNodeId The desired start node in the tree for the user.
allowMultiLogin True if multiple logins for the account are possible at the same time.
updateToken The update token may be used in external API calls modifying this account to improve security.

There are two system defined accounts:

  • the guest user. Everyone who is not logged in is treated as GUEST.

  • the supervisor. This user is in all roles and may operate on all mandators.

These two accounts can not be removed.

In the following we will look at how to create, update and remove accounts.

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.


After the account creation one can assign the roles the account is in and the groups it belongs to. For a detailed explanation of the meaning and functioning of roles and groups refer to the the section called “Security”.

For assigning a role to an account the following rules apply:

  • the caller must be in role ACCOUNT MANAGEMENT

  • the account/user has to belong to the callers mandator

  • the caller may only assign roles that he is assigned to himself

GROUP_GLOBAL_SUPERVISOR may set the roles for all users in the system.

Assigning a group to an account presumes the following prerequisites:

  • the caller must be in role ACCOUNT MANAGEMENT

  • the account/user has to belong to the callers mandator

  • the caller may only assign groups that also belong to his mandator, plus GROUP_EVERYONE and GROUP_OWNER

GROUP_GLOBAL_SUPERVISOR may set all groups for all users. Note that by default a newly created account is assigned to the group EVERYONE. To get more information about groups go to the the section called “Security”.

[fleXive] implements an access control list based approach to security combined with roles. Since handling access permissions on a per user basis would result in tremendous amounts of data, [fleXive] checks permissions based on access control lists on a per user group basis. User accounts can be assigned to any number of user groups and if in rare cases an explicit user based security is needed, the use of one group for each user is recommended.

User accounts are stored in the database and consist basically of the login name together with a hashed password of the assigned groups and roles. For more information about accounts see the section called “User Management”.

Mandators are - contrary to divisions - not transparent to the user but a means of separating accounts and data. Data can be shared between mandators by assigning user groups from multiple mandators to access control lists. Transfer of data between mandators is a planned upcoming feature of [fleXive]. An example when mandators should be used is e.g. to model different departments of a larger company.

Access control lists - which are assigned to user groups - define a list (Read, Edit, Create, etc.) of permissions attached to an arbitrary object like content instances, types, properties (and property assignments) or select lists. See this article on Wikipedia for more information about access control lists. For the purpose of easier organization and logical grouping [fleXive] categorizes ACL's into the following groups:

  • Instance: Attached to content instances.

  • Structure: Attached to types, properties and property assignments.

  • Workflow: Attached to workflow steps.

  • Briefcase: Attached to briefcases, to allow sharing them among different users.

  • Selectlist: Attached to select lists, the only relevant permission is Create to allow users to create new items for that list.

  • Selectlist Item: Attached to selectlist items, to restrict visibility.

Each access control list allows setting the following permissions independently: Read, Edit, Create, Delete, Relate and Export.

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:

  • GlobalSupervisor: no restrictions at all.

  • MandatorSupervisor: may do everything for "his" mandator

  • ACLManagement: create/update/delete ACL's for "his" mandator

  • AccountManagement: create/update/delete users, groups and roles (may only add roles he is assigned himself, may not alter assigned roles that he has not assigned himself) for "his" mandator. Everybody may read user and group informations (of course no passwords which are hashed anyways), but only for his own mandators unless he is a global supervisor.

  • SelectListEditor: may see the user interface to edit selectlist items (role entitles to no CRUD rights!), actual permissions are taken from the select lists createItemACL

  • WorkflowManagement: create/update/delete steps and workflows for "his" mandator

  • StructureManagement: create/update/delete types, relations, groups, properties, assignments and selectlists and assign scripts to structures for "his" mandator

  • ScriptManagement: create/update/delete scripts

  • ScriptExecution: execute scripts that can be run "standalone" (i.e. not triggered by events)

  • BackendAccess: may login to the backend (does not imply any rights)

One of the core tasks of [fleXive] is to store and query data. Like in relational databases or well-formed XML files, data needs to match a predefined structure. When [fleXive] was designed the requirements were as follows:

  • Simplicity: a very simple, intuitive and slim API
  • Hierarchical: the possibility to group properties together and nest them within subgroups
  • Reusability: if you define how a postal address looks like, you want to be able to reuse that definition
  • Inheritance: inheritance works like reusing a type to refine it
  • Multilingualism: every supported datatype should be able to store different data for different languages
  • Versioning: a user should have the possibility to create a new version of an instance
  • Security: if enabled, access control lists should restrict access to the type, properties, workflow steps and/or certain instances
  • Workflow: a content instance should always be assigned to a workflow step like "edit" or "live". Controlled by access control lists users may change the state following defined routes between states
  • Scripting: At predefined trigger points (like before or after creating a new data instance) scripts can be executed that have the possibility to alter data of the affected instance or perform arbitrary actions like sending emails

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).

To enable reuse of properties and groups these entities are independent of types and need to be assigned to types (and respectively groups). The benefit of this system - although it might sound a bit confusing at first glance - is that different types and assignments can share the same property which can be a big advantage for query operations [1] .

A special extension to types are relations (implemented in FxType, mode: Relation) which mimics the behaviour of attributed n:m relations known from SQL.

Structure elements can be addressed using XPath-like expressions as shown in the section called “Content Engine”.

Table 6.2. [fleXive] structure elements
Element Class Description
Type FxType 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).
Relation FxType (mode:Relation) A relation is basically a type that relates (or links) two other types together. A good analogy is an attributed relation known from SQL. It is possible to define how many times a specific instance may be used as a relation source or destination and which types may be related.
Property FxProperty A property defines a name and a datatype (and some options). Thats all there is to it! 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.
Group FxGroup A group serves as a container for properties and combines them to an entity. Groups - just like properties can not exist without assignments to types ( FxGroupAssignment). The purpose for their existance is like for properties: the ability to share and query across multiple types.
Assignment FxAssignment An assignment is the correlation of groups and properties to types. A group or property can only be used in instances if it is connected to a group assignment or a type.
Property assignment FxPropertyAssignment The assignment of a property to a group assignment or a type. If the property that is being assigned permits, settings like the access control list or options may be overridden.
Group assignment FxGroupAssignment The assignment of a group to a group assignment or a type. If the group that is being assigned permits, settings like the access control list or options may be overridden.

Following the convention on how to update or create new instances of classes in [fleXive], for every class exists (or should exist ;-) ) an editable class. These editable classes can either be instantiated with ClassName.createNew(..) or classInstance.asEditable() depending on if you want to create a new instance or edit an existing.

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).

The following is a list of parameters that can be passed as arguments to FxTypeEdit when editing or creating a new type:

Table 6.3. FxTypeEdit parameters
Parameter Method Create Edit Description
ACL setACL(ACL acl) X X The ACL which is checked when new instances of this type are created. Will only be checked if the type is configured to check permissions.
Category setCategory(TypeCategory category) X X A type can be assigned the categories User orSystem. A User categorized type can be edited by anyone with proper roles (StructureManagement), whereas System categorized types are ment to be [fleXive] internal and only to be changed by users with the role GlobalSupervisor. The mode may only be changed by users with the role GlobalSupervisor (under ordinary circumstances changing the category of a type should never be necessary).
Check validity setCheckValidity(boolean checkValidity) X X If set totrue, content instances can be assigned a validFrom and validUntil Date. FxContent instances provide anisValid(long time)-Method to check if they are valid at the requested time. This feature is particularly useful in queries since only valid content instances will be returned. Using this feature allows for instance time triggered publication (and removal) of articles.
Description setDescription(String description) X X Set a description for the type. Of relevance only to user interfaces.
Enable parent assignments setEnableParentAssignments(boolean enableParentAssignments) X - If a type is derived from another type, this flag decides if the derived assignments should be enabled. This is by default enabled when creating a derived type: FxTypeEdit.createNew(String name, FxString description, ACL acl, FxType parent) and can be disabled using this method before the derived type is saved.
History age setHistoryAge(long historyAge) X X If trackHistory is enabled for this type, the historyAge determines the duration for which history entries exist. All entries older than this time (in milliseconds) will be removed. History entries are changes to the type or instances and are not fully implemented yet.
Language mode setLanguage(LanguageMode language) X (X) Set one of the supported language modes:
  • None: Content is not language dependent
  • Single: One language per content may be defined
  • Multiple: Every property may exist in different languages
The language mode of existing types can only be changed if no content instances exist.
Maximum destination count (Relation) setMaxRelDestination(int maxRelDestination) (X) (X) Restrict the total number of instances that may be related to a source instance using this relation type. The value 0 means unlimited. This value can only be set if the type is a relation and no instances would invalidate this restriction.
Maximum source count (Relation) setMaxRelSource(int maxRelSource) (X) (X) Restrict the total number of instances that may be related to a destination instance using this relation type. The value 0 means unlimited. This value can only be set if the type is a relation and no instances would invalidate this restriction.
Maximum versions setMaxVersions(long maxVersions) X X Set the max. number of instance versions to keep, if negative unlimited, 0 does not keep any versions.
Mode setMode(TypeMode mode) X (X) Set if this type is to be used as a regular type or as a relation. Changing the mode is currently only allowed if no content instance exist. Possible modes are:
  • Content: The "regular" type
  • Relation: Type used as relation
Name setName(String name) X X The name of the type. Has to be unique.
Permissions setPermissions(byte permissions) X X Set the permissions to check. The parameter contains the bitcoded types of permissions that should be checked. Please use the setUseXXXPermission()-convenience methods, where XXX is Type, Property, Step or Instance. If you want to use bit coded permissions, use these constants:
  • FxPermissionUtils.PERM_MASK_TYPE
  • FxPermissionUtils.PERM_MASK_PROPERTY
  • FxPermissionUtils.PERM_MASK_STEP
  • FxPermissionUtils.PERM_MASK_INSTANCE
Remove instances with relation types setRemoveInstancesWithRelationTypes(boolean removeInstancesWithRelationTypes) - (X) Only applies to relations: If relation entries are removed (for instance, you no longer want to relate Type A and B using this relation), all instances of this relation type that relate the removed FxTypeRelation will also be removed.
State setState(TypeState state) X X Changing the state allows to (de-)activate a type.
  • Available
  • Locked - temporary unavailabilty, should only be set from [fleXive] internally to allow for timeconsuming processing.
  • Unvailable
Track history setTrackHistory(boolean trackHistory) X X Enables history tracking (will log changes to the type itself or instances). How long history entries are kept can be set with setHistoryAge(long)
Use instance permissions setUseInstancePermissions(boolean use) X X Should instance permissions be checked? If enabled, the ACL assigned to instances will be checked.
Use property permissions setUsePropertyPermissions(boolean use) X X Should property (assignment) permissions be checked? If enabled, the ACL assigned to property assignments will be checked. Property permission checks are disabled by default and should only be used if really necessary (i.e. if you want to hide specific company or department internal properties from users that under normal circumstances should be allowed to read the instance).
Use step permissions setUseStepPermissions(boolean use) X X Should step permissions be checked? If enabled, the ACL assigned to workflow steps will be checked. Enable these checks if you want to prevent users from seeing/using instances in certain steps (i.e. an editor should not be allowed to edit already published articles - this is something only users from the quality assurance department should be allowed to do).
Use type permissions setUseTypePermissions(boolean use) X X Should type permissions be checked? If enabled, the ACL assigned to this type will be checked. Disabling this check, will allow everyone to create or remove instances of this type (if instance permission checks are enabled, they will of course still be checked in the case of a removal).
Workflow setWorkflow(Workflow workflow) X (X) Assign a workflow to this type. For existing types the workflow can only be changed if no instances exist.

In the following example we create a new type "Customer", provide a multilingual description and assign an access control list:

Example 6.4. Creating a new FxType


Another way to create a new type would be to use the GroovyTypeBuilder:


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

Table 6.4. [fleXive] data types
Data type FxValue class Description
HTML FxHTML HTML markup. Unlimited in length. Offers the ability to use HTML editors in user interfaces.
String1024 FxString A String with a maximum length of 1024 characters. Use this data type in favor of Text if you don't need more than 1024 characters, since usually Text is stored in CLOB Database columns while String1024 uses VARCHAR columns.
Text FxString Like String1024 but unlimited in length.
Number FxNumber Numerical type corresponding to the Java Integer class.
LargeNumber FxLargeNumber Numerical type corresponding to the Java Long class.
Float FxFloat Numerical type corresponding to the Java Float class.
Double FxDouble Numerical type corresponding to the Java Double class.
Date FxDate A date corresponding to the Java Date class. Note that there is no time information saved!
DateTime FxDate A date corresponding to the Java Date class. This data type stores date and time information.
DateRange FxDateRange A date range corresponding to two Java Date class instances with a start- and enddate. Note that there is no time information saved!
DateTimeRange FxDateTimeRange A date range corresponding to two Java Date class instances with a start- and enddate. Time information is saved as well using this data type.
Boolean FxBoolean A boolean value corresponding to the Java Boolean class.
Binary FxBinary This data type stores information about a binary content and allows streaming of that content. For more information please refer to the section called “Handling binary content”
Reference FxReference A reference to a content instance, identified by its primary key (FxPK).
InlineReference - This data type is only planned but not implemented. It will allow to create contents that do not exist on their own (and can not be loaded on their own or queried for) but embedded in another content instance. Their XPath addressing will be relative to their parent group in the embedding content.
SelectOne FxSelectOne This data type allows the selection of one entry of a SelectList. See the section called “Select lists” for further information about select lists.
SelectMany FxSelectMany This data type allows the selection of many entries of a SelectList. See the section called “Select lists” for further information about select lists.

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.

While only users in the role of SelectListEditor may create, update and delete select lists, select list items are handled differently. Whether a specific user is permitted to add itmes to and remove items from a specific select list is handled by the createItem ACL of the select list. Whether users may read, edit, select and deselect a specific select list item is handled by the ACL of the select item itsself. The operations and relevant permissions are specified in Table 6.7, “Relevant permissions for working with select list items”.

Table 6.7. Relevant permissions for working with select list items
Operation ACL Permission Description
Creating a select list item FxSelectList.createItemACL CREATE The createItemACL of the item's select list controls which users may create and hence add select list items to this specific select list.
Deleting a select list item FxSelectList.createItemACL DELETE Similar to the creation of new select list items, the createItemACL of the item's select list also controls which users may remove select list items from this specific select list.
Editing a select list item FxSelectListItem.acl EDIT Whether a user may change the data of a specific select list item is controlled by the EDIT permission of the ACL of the select list item itsself.
Reading a select list item FxSelectListItem.acl READ Whether a user may read a specific select list item and its data (for exmaple in the content editor) is controlled by the READ permission of the select list item.
Adding a select list item to a selection (when working with contents) FxSelectListItem.acl READ, CREATE Whether a user may add specific select list item to his seleciton is controlled by the READ (otherwise the user wouldn't see that the item exists) and by the CREATE permission of the select list item.
Removing a select list item to a selection (when working with contents) FxSelectListItem.acl READ, DELETE Whether a user may remove specific select list item from his seleciton is controlled by the READ (otherwise the user wouldn't see that the item exists) and by the DELETE permission of the select list item.

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(..).

Example 6.7. Creating new properties

1        AssignmentEngine assignmentEngine = EJBLookup.getAssignmentEngine();
2        ACL customerACL = CacheAdmin.getEnvironment().getACL(ACL.Category.STRUCTURE.getDefaultId());

3        FxPropertyEdit name = FxPropertyEdit.createNew("Name",
4                        new FxString("Name of the person"),
5                        new FxString("Enter the persons name"),
6                        FxMultiplicity.MULT_1_1,
7                        customerACL,
8                        FxDataType.String1024);
9        assignmentEngine.createProperty(typeId, name.setAutoUniquePropertyName(true), "/");

1

Obtain a reference to the assignment engine bean which is responsible for manipulating assignments

2

Get the default ACL used for structures

3

Create a new property with the alias "Name"

4

Description

5

Hint for user interfaces

6

Configure this property to be required (See the section called “Multiplicity” for more information)

7

Assign the ACL to be used. This ACL will only be checked if the type this property will be assigned to has property permission checks enabled

8

The data type will be a String with a maximum length of 1024 characters. See the section called “Data types” for an overview of available data types.

9

Since properties can not exist if they are not assigned to a type, we assign them to the type with the id typeId to the root group ("/" - for an example how to assign it to a group of choice see the section called “Groups and group assignments”). Property names have to be unique but since "Name" is very likely to be used by another property already we allow [fleXive] to auto-generate a unique property name (in the form of "propertyname_"+running number) and make use of the feature that most setters return the object itself (in this case the FxPropertyEdit object) which we pass to the createProperty(..)-method. This method will create the property and assign it to the type we passed as first argument - creating a new property and property-assignment entry.


To reuse an existing property-assignment is even simpler:


The following is a list of parameters that can be passed as arguments to FxPropertyEdit and FxPropertyAssignmentEdit when editing or creating a new propery/assignment:

Table 6.8. FxPropertyEdit/FxPropertyAssignmentEdit shared parameters
Parameter Method Create Edit Description
ACL setACL(ACL acl) X X The ACL which is checked when the type using this property or assignment is configured to check property permissions. Setting this value for FxPropertyAssignmentEdit is only allowed if the referenced property allows to override its ACL.
Hint setHint(FxString hint) X X Set a hint text to be displayed in user interfaces.
In overview setInOverview(boolean inOverview) X X Display in overviews. This is an option for user interfaces and a convenience method to set an option (See the section called “Property and group options”). The constant FxStructureOption.OPTION_SHOW_OVERVIEW ("SHOW.OVERVIEW") is used. The property can restrict this setting from being overwritten in an assignment.
Label setLabel(FxString label) X X Set a label text to be displayed in user interfaces.
Multilingual setMultiLang(boolean multiLang) X X Allow multilingual values for this property. This is a convenience method to set an option (See the section called “Property and group options”). The constant FxStructureOption.OPTION_MULTILANG ("MULTILANG") is used. The property can restrict this setting from being overwritten in an assignment.
Multiline setMultiLine(boolean multiLine) X X A hint for user interfaces if this property should be rendered using input elements with multiple lines. Useful for String/Text based properties (See the section called “Data types”) which should be displayed in a textarea instead of a single input field. Decision how to render the component is up to the user interface. This is a convenience method to set an option (See the section called “Property and group options”). The constant FxStructureOption.OPTION_MULTILINE ("MULTILINE") is used. The property can restrict this setting from being overwritten in an assignment.
Multiplicity setMultiplicity(FxMultiplicity multiplicity) X (X) Set the multiplicity of this property. Can only be changed if no instances exist that would violate the new setting. (See the section called “Multiplicity” for more information). The property can restrict this setting from being overwritten in an assignment.
Options setOption(..) setOptionOverrideable(..) clearOption(..) X X Option related operations. See the section called “Property and group options”.
Searchable setSearchable(boolean searchable) X X Allow user interfaces to use this propery/assignment in visual query editors. This is a convenience method to set an option (See the section called “Property and group options”). The constant FxStructureOption.OPTION_SEARCHABLE ("SEARCHABLE") is used.
Use HTML editor setUseHTMLEditor(boolean useHTMLEditor) X X Hint for user interfaces to use a HTML editor when editing values of this property. Only makes sense for String/Text based data types. This is a convenience method to set an option (See the section called “Property and group options”). The constant FxStructureOption.OPTION_HTML_EDITOR ("HTML.EDITOR") is used.

Table 6.9. FxPropertyEdit exclusive parameters
Parameter Method Create Edit Description
Auto unique property name setAutoUniquePropertyName(boolean autoUniquePropertyName) X - Property names have to be unique to allow querying them. Setting this option to true will automatically choose a name that has not been used for a propery by adding an underscore and a running number to property names until it is unique. Set this option only if you do not plan on "sharing" a property between different types or dont need to query based on properties but rather property assignments.
Data type setDataType(FxDataType dataType) X - Set the data type of this property. Please see the section called “Data types” for more information.
Fulltext indexed setFulltextIndexed(boolean fulltextIndexed) X X Enable fulltext indexing and queries for a property. See the section called “Fulltext search” for more information.
Name setName(String name) X - Set the name of this property. This name is used in assignments as a proposal for the XPath alias (unless a different one is requested). Currently the name can not be changed for existing properties. To query across assignments using the same property, this name is used.
Overrideable ACL setOverrideACL(boolean overrideACL) X X Restrict if assignments may use an ACL different from the one defined for the property. If set to false an assignment may still set an ACL but the ACL of the property is used and the assignments is ignored.
Overrideable HTML editor setOverrideHTMLEditor(boolean overrideHTMLEditor) X X Restrict assignment to override the HTML editor option (User interface hint). This is a convenience method to set an option (See the section called “Property and group options”). The constant FxStructureOption.OPTION_HTML_EDITOR ("HTML.EDITOR") is used.
Overrideable Multilinguality setOverrideMultiLang(boolean overrideMultiLang) X X Restrict assignment to override the multilinguality option (allow multilingual values). This is a convenience method to set an option (See the section called “Property and group options”). The constant FxStructureOption.OPTION_MULTILANG ("MULTILANG") is used.
Overrideable Multiline setOverrideMultiLine(boolean overrideMultiLine) X X Restrict assignment to override the multiline option (User interface hint). This is a convenience method to set an option (See the section called “Property and group options”). The constant FxStructureOption.OPTION_MULTILINE ("MULTILINE") is used.
Overrideable multiplicity setOverrideMultiplicity(boolean overrideMultiplicity) X X Restrict if assignments may override the multiplicity of this property. (See the section called “Multiplicity” for more information).
Overrideable Overview setOverrideOverview(boolean overrideOverview) X X Restrict assignment to override the overview option (User interface hint). This is a convenience method to set an option (See the section called “Property and group options”). The constant FxStructureOption.OPTION_SHOW_OVERVIEW ("SHOW.OVERVIEW") is used.
Overrideable Searchable setOverrideSearchable(boolean overrideSearchable) X X Restrict assignment to override the searchable option (User interface hint). This is a convenience method to set an option (See the section called “Property and group options”). The constant FxStructureOption.OPTION_SEARCHABLE ("SEARCHABLE") is used.
Referenced list setReferencedList(FxSelectList referencedList) X (X) If the properties data type is SelectOne or SelectMany (See the section called “Data types” for more information) the referenced selectlist (See the section called “Select lists”) can be assigned. Updating an existing property is only allowed if no data instances using the original selectlist exist.
Referenced type setReferencedType(FxType referencedType) X (X) If the properties data type is Reference (See the section called “Data types” for more information) the referenced type (See the section called “Types”) can be assigned. Updating an existing property is only allowed if no data instances using the original type exist.
Unique mode setUniqueMode(UniqueMode uniqueMode) X (X) Set the uniqueness level of this property. May only be changed if no content instances using this property exist. (See the section called “Uniqueness of values” for more information).

Table 6.10. FxPropertyAssignmentEdit exclusive parameters
Parameter Method Create Edit Description
Alias setAlias(String alias) X - Set the alias of a property assignment. Property assignments may define an alias to allow multiple use of the same property but using a different name. The alias is the rightmost part of the XPath used to address an assignment. Changing an alias for existing assignments is not supported (yet).
Default language setDefaultLanguage(int language) X X Defining a (optional) default language preselects this language in multilingual values as the default language.
Default multiplicity setDefaultMultiplicity(int defaultMultiplicity) X X The default multiplicity determines how many values will be initialized for an assignment. Useful in user interfaces to pre-create a set of entries instead of one.
Enabled setEnabled(boolean enabled) X (X) Enables or disables a property assignment - making it unavailable to editors, etc. Updating an existing assignment is currently experimental and might have side-effects ...
Parent group assignment setParentGroupAssignment(FxGroupAssignment parent) X - If this assignment is assigned to a group, the assignment of the parent group (in the context of the current type)
Position setPosition(int position) X X Set the position of the assignment (within the same parent group). Changing an assignment's position will be update all other affected assignments within the same group. Invalid values will be adjusted (to 0 or the max. possible position)

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(..).

Example 6.9. Creating a new group

1        AssignmentEngine assignmentEngine = EJBLookup.getAssignmentEngine();

2        assignmentEngine.createGroup(
3                typeId,
4                FxGroupEdit.createNew(
5                        "Address",
6                        new FxString("The customers address"),
7                        new FxString("Enter the customers address here"),
8                        true,
9                        FxMultiplicity.MULT_1_1).
10                        setAssignmentGroupMode(GroupMode.AnyOf),
11                "/");

12        FxPropertyEdit street = FxPropertyEdit.createNew(...);
13        FxPropertyEdit zip = FxPropertyEdit.createNew(...);
14        assignmentEngine.createProperty(typeId, street, "/Address");
15        assignmentEngine.createProperty(typeId, zip, "/Address");

1

Obtain a reference to the assignment engine which is needed to create groups, properties and (of course) assignments

2

We're about to create a new group

3

Since groups can not be created without assigning them to a type, we have to provide the id of the type we want to assign this group to.

4

The second parameter to AssignmentEngine.createNew(..) is a new FxGroupEdit instance.

5

"Address" is the name we chose for the new group

6

The label (for user interfaces)

7

The hint (for user interfaces again)

8

This parameter allows overriding the multiplicity assigned in the next line by assignments to the group

9

We make the group required, setting the multiplictiy to 1..1 (See the section called “Multiplicity” for more information)

10

This parameter is optional, since it is the default value. We set the group mode to allow any of the group's children to be present. An alternative would be OneOf where only one child of the group may be set. (See the section called “Group modes” for more information)

11

We need to provide the XPath relative to the root group of the type where we want to assign the group to. Using "/" will assign it directly to the root group.

12

We create a property called "Street" which we want to assign to the address group later.

13

Same for the property "ZIP"

14

The "Street" property is created like in the section called “Properties and property assignments”, but we assign it to our new created group "/Address"

15

And again for the "ZIP" code


Here's another example for creating groups using the GroovyTypeBuilder and for attaching content using the GroovyContentBuilder:

Example 6.10. Creating a new group using the GroovyTypeBuilder

        import com.flexive.shared.scripting.groovy.*
        import com.flexive.shared.value.*
        import com.flexive.shared.security.*
        import com.flexive.shared.*
        import com.flexive.shared.structure.*

1      new GroovyTypeBuilder().person(description: new FxString("Person"),
2                acl: CacheAdmin.environment.getACL(ACL.Category.STRUCTURE.defaultId),
3                multilang: true) {
4                    firstname(dataType: FxDataType.String1024,
                        multilang: false,
                        description: new FxString(FxLanguage.ENGLISH, "First name"),
                        multiplicity: FxMultiplicity.MULT_0_N)

5                    lastname(assignment: "PERSON/FIRSTNAME",
                       description: new FxString(FxLanguage.ENGLISH, "Last name"),
                       hint: new FxString(FxLanguage.ENGLISH, "Last name required"),
                       multiplicity: FxMultiplicity.MULT_1_N)

6                    ADDRESS(description: new FxString(FxLanguage.ENGLISH, "Address"),
                        multiplicity: FxMultiplicity.MULT_0_N) {

7                         street(dataType: FxDataType.String1024,
                             description: new FxString(FxLanguage.ENGLISH, "Street (Nr)"),
                             multiplicity: FxMultiplicity.MULT_0_N)
                     }
        }

8      def builder = new GroovyContentBuilder("PERSON")

9      builder {
10           firstname("John")
11           lastname("Doe")
12           address {
13               street(new FxString(false, "Ameaningfulstreetname 444"))
            }
         }
14       EJBLookup.getContentEngine().save(builder.getContent())

1

Create the type "Person" using the GroovyTypeBuilder ..

2

.. use the default ACLs ..

3

.. and set the type to support multiple languages.

4

Create the first property "firstname".

5

Another property for the last name (implicitly required because auf the default multiplicity of 1..N), which is a derived assignment from "FIRSTNAME".

6

Here, the group "Address" having the XPath "ADDRESS" is created. Important: UPPERCASE LETTERS (Either the whole group name or simply the first letter, as in "Address") always denote the creation of a Group.

7

The group's only property: "street".

8

Retrieve a GroovyContentBuilder instance.

9

Call the builder passing the parameters (XPathname([contentValue]):

10

Set the firstname to "John".

11

Set the lastname to "Doe".

12

"Open up" the group's XPath value using "address".

13

Pass the value "Ameaningfulstreetname 444" to the XPath ADDRESS/STREET

14

Save the content by retrieving the ContentEngine EJB and calling its save() method.


The following is a list of parameters that can be passed as arguments to FxGroupEdit and FxGroupyAssignmentEdit when editing or creating a new group/assignment:

Table 6.11. FxGroupEdit/FxGroupAssignmentEdit shared parameters
Parameter Method Create Edit Description
Assignment GroupMode setAssignmentGroupMode(GroupMode mode) X (X) Set the group mode to allow any of its possible children or just one to be present. Can only be changed for existing groups/assignments if no instances exist (See the section called “Group modes” for more information)
Hint setHint(FxString hint) X X Set a hint text to be displayed in user interfaces.
Label setLabel(FxString label) X X Set a label text to be displayed in user interfaces.
Multiplicity setMultiplicity(FxMultiplicity multiplicity) X (X) Set the multiplicity of this group. Can only be changed if no instances exist that would violate the new setting. (See the section called “Multiplicity” for more information). The group can restrict this setting from being overwritten in an assignment.
Options setOption(..) setOptionOverrideable(..) clearOption(..) X X Option related operations. Seethe section called “Property and group options”.

Table 6.12. FxGroupEdit exclusive parameters
Parameter Method Create Edit Description
Name setName(String name) X - Set the name of this group. This name is used in assignments as a proposal for the XPath alias (unless a different one is requested). Currently the name can not be changed for an existing group.
Overrideable multiplicity setOverrideMultiplicity(boolean overrideMultiplicity) X X Restrict if assignments may override the multiplicity of this group. (See the section called “Multiplicity” for more information).

Table 6.13. FxGroupAssignmentEdit exclusive parameters
Parameter Method Create Edit Description
Alias setAlias(String alias) X - Set the alias of a group assignment. Group assignments may define an alias to allow multiple use of the same group but using a different name. The alias is part of the XPath and is used to address an assignment. Changing an alias for existing assignments is not supported (yet).
Default multiplicity setDefaultMultiplicity(int defaultMultiplicity) X X The default multiplicity determines how many values will be initialized for an assignment (i.e. how many groups are created upon initialization). Useful in user interfaces to pre-create a set of entries instead of one.
Enabled setEnabled(boolean enabled) X (X) Enables or disables a group assignment - making it unavailable to editors, etc. Updating an existing assignment is currently experimental and might have side-effects ...
Parent group assignment setParentGroupAssignment(FxGroupAssignment parent) X - If this assignment is assigned to a group, the assignment of the parent group (in the context of the current type)
Position setPosition(int position) X X Set the position of the assignment (within the same parent group). Changing an assignments position will be upate all affected other assignments within the same group. Invalid values will be adjusted (to 0 or the max. possible position)

When the persistence engines (structure and content) of [fleXive] were designed, we tried to solve this problem by using a generic approach (unlike hibernate, which accesses data instances with (auto)generated classes). Since we wanted to use hierarchical data structures which are quite like XML in nature, the weapon of choice was an XPath-like approach: Values are accessed using their XPath.

As a simple example lets consider the following XML file:

<?xml version=“1.0“ standalone=“yes“?>
<Person>
    <Name>Max Muster</Name>
    <Phone>+43 1 12345</Phone>
    <Phone>+43 1 800 FLEXIVE</Phone>
    <Address>
        <Street>Private road</Street>
    </Address>
    <Address>
        <Street>Office lane</Street>
    </Address>
</Person>

With [fleXive] we would create a type called Person. Using the GroovyTypeBuilder we would execute the following code in the groovy console:


Lets have a look at the following table, which is based on the XML data example, to visualize the mapping of XPath's to values:

Table 6.15. XPath to value mapping
XPath Value
PERSON/NAME[1] Max Muster
PERSON/PHONE[1] +43 1 12345
PERSON/PHONE[2] +43 1 800 FLEXIVE
PERSON/ADDRESS[1]/STREET[1] Private road
PERSON/ADDRESS[2]/STREET[1] Office lane

The XPath starts with the name of the type (which is optional if addressing in a FxContent instance, since there the type if obviously known but is needed for example in query results) and the path to address the property. Please note that XPaths are not case-sensitive and that an index of 1 is optional: PERSON/ADDRESS[2]/STREET[1] for example is identical to PERSON/ADDRESS[2]/STREET.

FxContent serves as a container for groups, properties and general information about a content instance. It is used to initialize (create an empty content instance), create, save and load content instances [2] .


The purpose of this example is to demonstrate how easy it is to create, update and remove content instances. Since a content instance is tied to a type (See the section called “Types” for more information) the first thing that needs to be done is to initialize a new (empty) content instance 1. Initializing a content instance creates as many property or group entries as defined in the respective assignments' default multiplicity. Setting a value to a property assignment 2 is done by creating a new FxValue instance corresponding to the property's data type for the XPath of the assignment. The same applies if a group is involved, as shown in 4 for the street property of the first address group. Adding a new index is done by simply setting the XPath to the desired value like in 3 or 5. Please note that using an index of 3 would be illegal if no index of 2 exists.

Removing an XPath is as simple as calling co.remove("/Address[2]") if the second address group should be removed.

A content is created 6 and updated by calling the ContentEngine's FxPK save(FxContent content) method which returns the primary key of a content instance. Loading is done by providing the primary key to the ContentEngine's load(FxPK pk)-method. 7.

Changing a value can be done by assigning a new FxValue instance (like in 5) or by reading the current value 8, and changing it 9 which is updated in the content instance as can be seen from the println command on the application servers console.

To remove a content instance (10) only the primary key - and all required permissions - is needed.

To be able to identify a content, a primary key (implemented in FxPK) is needed. This primary key consists of the unique identifier (usually equivalent to the id the content is stored in the database with) and the version. Depending on the configuration of the type the content belongs to it is possible to create different versions of a content.

A primary key can consist of a distinct version (a numerical value) or a predefined constant:

  • MAX: Constant to select the maximum (highest) available version

  • LIVE: Constant to select the version whose workflow step is flagged as live

To create a new version simply call the ContentEngine's createNewVersion(FxContent co) method.

Information about all versions of a content can be retrieved using the ContentEngine's FxContentVersionInfo getContentVersionInfo(FxPK id) method. FxContentVersionInfo contains information about the minimum-, maximum- and most recently modified version numbers as well as information which user was the last to update each version and if a live version exists.

[fleXive] contents can be queried using a SQL-like dialect called FxSQL. The core idea of FxSQL is to provide a flat virtual table that contains all content instances visible to the current user, with full support for [fleXive] data types and multilingualism.

While it is possible to submit queries in plain FxSQL, there are alternatives for Java and Groovy developers in the form of query builders. They handle proper formatting of values and are the preferred way of formulating queries unless you need some of the more esoteric features of FxSQL.

The overall query layout is similar to SQL. Currently queries are always on the virtual table "content" that provides a flat view on all content instances.

SELECT @pk, caption           -- 1
FILTER version=live              -- 2
WHERE caption LIKE 'test%'       -- 3
ORDER BY caption                 -- 4

1

We select the virtual property @pk (the content primary key) and the standard property caption.

2

Filters work similar to the SQL HAVING clause by providing a post-processing filter mechanism on the results of the actual query. That is, filters are applied every time the search query is executed, and are not stored in the cached result tables. This means that changing filters usually does not invalidate the query cache, whereas changing the WHERE clause always does. In this example, we might want to select only live versions. If you do not specify a version filter, the search uses the maximum version of contents for matching conditions and selecting properties.

3

The WHERE clause supports most standard SQL operators for string and numerical comparisons. Here we select all contents whose caption starts with "test". Note that string comparisons are case insensitive.

4

To control the sorting of the result set, you can specify one or more columns in the ORDER BY clause. By default an ascending sort is used, to sort by descending values add DESC to the column alias (e.g. ORDER BY id DESC). Note that you can only use columns that are specified in the SELECT clause.

The rest of this section contains an enumeration of FxSQL features along with example queries demonstrating that feature.

Of course you can select all system properties, like acl or created_by, in your query. Some system properties are linked to their backing table. For example, the acl property is linked to the FXS_ACL table, so you can select any column in that table using a field suffix: acl.description selects the description column, and acl.color returns the color code. The most useful field, however, is the virtual acl.label field that returns the ACL label in the calling user's language.

Another useful example is to select the user name that created a content, instead of the account ID:

SELECT @pk, created_by.username

The following table contains all system properties that are linked to their backing table, including the most important fields. For a complete field list, please refer to the database schema.

Table 6.17. System property fields provided in FxSQL
Property (Table) Fields
acl (FXS_ACL) Selects the content ACL. Additional fields include:
acl.label

The localized label in the calling user's language.

acl.name

The unique name of the ACL.

acl.description

The ACL description.

acl.cat_type

The ACL category.

acl.color

The RGB color code used for this ACL.

created_by, modified_by (FXS_ACCOUNTS) Selects the user that has created/lastly modified the content ( created_by and modified_by both have the same fields). Interesting fields include:
created_by.username

The associated user's username.

created_by.email

The associated user's email address.

created_by.login_name

The unique login name of the user.

mandator (FXS_MANDATOR) Selects the mandator of the content instance. To select the mandator name, use mandator.name.
step (FXS_WF_STEPS) Selects the workflow step of the content instance. You can select the following fields:
step.label

The localized step label in the calling user's language.

step.workflow

The workflow ID of the step (and thus the complete workflow used for this content instance).

step.stepdef

The step definition ID.

step.acl

The ACL of the step.

To control the sort order of the result set, you can specify one or more columns in the ORDER BY clause. Usually you specify the name of a column previously selected in the SELECT clause, but you can also use the 1-based column index. The direction of the sort (ascending or descending) is set using the ASC and DESC modifiers, respectively. The following two queries order the result by the properties priority and caption (i.e. first the result is sorted by priority, then by caption), the first uses named columns, the second specifies the column indices instead:

SELECT @pk, caption, priority
ORDER BY priority DESC, caption

SELECT @pk, caption, priority
ORDER BY 3 DESC, 2

As described in the section called “Select user-defined columns”, @* expands to whatever columns the user defined for the result content type. This causes a problem when the result should be sorted manually by one of these columns, e.g. because the result table has sortable column headers (as in the result table in the backend administration application): the FxSQL parser has no way to expand @* (because the search has not been submitted yet and thus the content type is unknown), but yet it must be possible to sort by one of these columns. For example, this query does not work:

SELECT @*
ORDER BY caption DESC     -- caption not found in SELECT clause

As a workaround, it is possible to specify otherwise invalid column indices in the ORDER BY clause if @* was selected. Of course this may lead to runtime errors if the user-defined columns are less than the ORDER BY index. In the most probable use case, on-the-fly sorting of a result table, this is not a problem, since the user can only sort by columns that have already been rendered.

For example, the following is a valid FxSQL query but relies on the user having defined at least 3 columns for the result type:

SELECT @*
ORDER BY 3 DESC     -- order by the third column of @*

To ease the pain of having to learn yet another query language, the SqlQueryBuilder provides a thin builder interface for FxSQL queries. The query is created using chained calls to the builder and results in a FxSQL query. For example:

new SqlQueryBuilder()                                   // 1 
     .select("@pk", "created_at", "caption")            // 2
     .type("article")                                   // 3
     .orderBy("created_at", SortDirection.DESCENDING)   // 4
     .getResult();                                      // 5

1

A new query builder is created.

2

We select three columns, the virtual property @pk, the content creation date, and the article caption.

3

We want to search only for contents of type Article.

4

Order the result by creation date, return newest articles first (SortDirection.DESCENDING). You can issue multiple calls to orderBy for sorting by multiple columns. You can also specify the column index instead of the column name. If you specify the property name, you must ensure that this property is selected, otherwise the query builder throws a FxRuntimeException.

5

The getResult() call submits the search query to the search engine EJB and returns a FxResultSet.

A call to SqlQueryBuilder#getQuery() returns the actual FxSQL query, for example, the code snippet above built this FxSQL query:

SELECT @pk, created_at, caption
WHERE (typedef = 3)
ORDER BY created_at DESC

The basic query condition specifies

  1. a property or assignment whose value will be compared,

  2. a PropertyValueComparator specifying the compare operator (like equals or greater), and

  3. a constant value to compare the content value against, like "5" or "Test". Comparisons between content values are not supported.

SqlQueryBuilder offers an overloaded, general-purpose condition() method for specifying arbitrary conditions, and custom condition methods for tree queries and content type constraints:

condition(...)

Add a condition to the query. This method is overloaded to support both assignment and property queries, for the actual method signatures please refer to the [fleXive] JavaDoc. If you want to apply a function (e.g. YEAR(prop)), you have to use the generic condition(String, ...) methods.

isChild(nodeId)

Adds a tree search condition to the query that limits the search to children (direct and indirect) of the given tree node ID. See the section called “Tree Search”.

isDirectChild(nodeId)

Like isChild, but includes only direct children of the given node.

type(contentType)

Adds a content type constraint to the query, i.e. the expression will match only contents of the given type. Note that this is semantically different from a content type filter, which will be covered in the next section.

When a FxSQL query is submitted to the database, all rows are fetched at once and returned in a FxResultSet object. It contains all result rows within the user-defined limits (unlike the cursor-approach of JDBC), including miscellaneous information like the selected column names, or row count information.

[fleXive] comes with a tree component, accessible via the TreeEngine interface with means to create and manage tree based structures and attach FxContent instances to tree nodes. There are actually 2 logically (and physically in terms of used database tables) distinct trees: a live (published) and an edit (preview) tree. There always exists a virtual root node with node Id 1 defined in FxTreeNode.ROOT_NODE . If there is no content manually attached, [fleXive] will create an instance of type Folder and attach it. The same thing applies if a content instance that is attached to a node is removed: it will be replaced by an autogenerated Folder instance. An exception is removal of a content linked to a leaf node. In this case the tree node will be removed as well.

The workflow engine is responsible for creating and maintaining workflows. Unless you need to create your own workflows programmatically, the most important information in this section is the conceptual overview which explains the basic concepts of the workflow engine. The [fleXive] workflow engine is a specialized workflow implementation used by the content engine, it does not offer a generic workflow implementation.

A workflow combines a collection of workflow states and the enumeration of all possible transitions between those states. In [fleXive], the following terminology is used:

Step definition

An abstract definition of a workflow step. It defines a localized label and a unique target.

Unique target

Supports the concept of unique steps for versioned contents. When a workflow step with a unique target is assigned to a content instance version, all other versions of the instance that are in the same workflow step are moved to the unique target step. Since this transition is executed every time a content instance is saved, there can be at most one content instance version in a step with a unique target at any given time.

The canonical example for this is the Edit/Live/Archived workflow for publishing website contents: a content is created in the Edit workflow step. When it is deemed to be ready for publication, the latest version is set to the Live workflow step and is shown on the web page. When an update is necessary, a new version is created in the Edit workflow step which can be modified without altering the Live instance. When the new version is to be published, it is set to the Live workflow step. However, there already exists an old version in the Live step: to resolve this, the Live step has a unique target (e.g. Archived). When the latest version is set to the Live step, the previous Live version is moved to the Archived step.

Workflow

A concrete workflow that consists of steps and routes, including the permission configuration for both.

Step

A concrete assignment of a step definition to a workflow, including an ACL that defines the permissions on objects in this workflow step.

Route

A transition between two steps of a workflow, including the user group for which it should be available.

Although workflows can be edited in the backend administration application, you can also setup new workflows programmatically. The workflow engine is spread across four EJB interfaces, each one handling the create/update/delete operations for its part of the workflow: step definitions, steps, routes, and the workflow objects themselves. We'll show how to create a simple workflow from scratch, for a more elaborate explanation of the methods please refer to the [fleXive] JavaDoc.


Example 6.20. Creating a new workflow with steps and routes

There are EJB interfaces for adding steps and routes to an existing workflow. However, when we create a new workflow we would have to first create an empty workflow, and then create each step and route using EJB calls. To simplify things a bit, the workflow engine can create the steps and routes for a new workflow object using intermediate IDs. An intermediate step or route ID is negative (IDs retrieved from the database are always positive) and can be referenced in routes. Finally we retrieve the created workflow from the environment (workflows are always cached, so there isn't even a method to load workflows directly from the database) and perform some validity checks.

// create a workflow and auto-create steps using intermediate IDs
final Step step1 = new Step(-10, definition1.getId(), ACL.Category.WORKFLOW.getDefaultId());
final Step step2 = new Step(-20, definition2.getId(), ACL.Category.WORKFLOW.getDefaultId());

// create a route between step1 and step2
final Route route = new Route(-1, UserGroup.GROUP_EVERYONE, -10, -20);

// create workflow object and store it in the database
final Workflow workflow = new Workflow(-1, "test wf", "my test workflow",
        Arrays.asList(step1, step2), Arrays.asList(route));
final long workflowId = EJBLookup.getWorkflowEngine().create(workflow);

final Workflow dbWorkflow = CacheAdmin.getEnvironment().getWorkflow(workflowId);
assert dbWorkflow.getRoutes().size() == 1;      // route available?
assert dbWorkflow.getSteps().size() == 2;       // both steps available?

// check from and to steps of our route
assert dbWorkflow.getRoutes().get(0).getFromStepId() == dbWorkflow.getSteps().get(0).getId();
assert dbWorkflow.getRoutes().get(0).getToStepId() == dbWorkflow.getSteps().get(1).getId();

The configuration engine provides a hierarchical storage for configuration properties. It allows to override default parameters with user-specific settings, and uses the distributed cache to avoid database lookups.

A parameter is defined using one of the ParameterFactory factory methods. The parameter interface uses Java generics to provide typesafe manipulation of the configuration values, for example it is not possible (using the configuration APIs) to store a String value in an Integer parameter. Let's start with declaring a configuration parameter of type Integer:

public static final Parameter<Integer> INT_PARAM =
    ParameterFactory.newInstance(
        Integer.class,       /* value class */
        "/config/test",      /* path */
        ParameterScope.USER,
        "param1"             /* key */,
        21                   /* default value */
    );

Our new parameter uses user scope, which (by definition) uses the division configuration as a fallback. This means we can now store values both in the division and user configuration. Of course, unless we are logged in as a global supervisor, we cannot update the division configuration, but any user can update his or her own configuration. By default, the configuration engine uses the "least shared" scope, in our case the user scope. The following call puts a value in the configuration of the calling user and displays the new value:

EJBLookup.getConfigurationEngine().put(INT_PARAM, 1