In two short steps, you can have a new plugin-project up and running; this can be done using Forge itself!

That's it! Now your project is ready to be compiled and installed in Forge, but you may still want to add some commands.

If you do not wish to create a new plugin project using Forge itself, you will need to manually include the Forge-API dependencies. For purposes of simplicity, we have pasted a sample Maven POM file which can be used as a starting point for a new plugin:

<?xml version="1.0" encoding="UTF-8"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
                             http://maven.apache.org/xsd/maven-4.0.0.xsd" 
    xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example.plugin</groupId>
  <artifactId>example</artifactId>
  <version>1.0.0-SNAPSHOT</version>

  <properties>
    <forge.api.version>[1.0.0-SNAPSHOT,)</forge.api.version>
  </properties>
  
  <dependencies>
    <dependency>
      <groupId>org.jboss.seam.forge</groupId>
      <artifactId>forge-shell-api</artifactId>
      <version>${forge.api.version}</version>
    </dependency>
  </dependencies>
  
  <repositories>
    <repository>
      <id>jboss</id>
      <url>https://repository.jboss.org/nexus/content/groups/public/</url>
    </repository>
  </repositories>
  
  <build>
    <plugins>
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <source>1.6</source>
          <target>1.6</target>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Default commands must be annotated with @DefaultCommand, and are not named; you may still provide help text or command metadata. Each plugin may have only one @DefaultCommand.

The following default command would be executed by executing the plugin by its name:

public class ExamplePlugin implements Plugin {
   @DefaultCommand
   public void exampleDefaultCommand( @Option String opt ) {
      // this method will be invoked, and 'opt' will be passed from the command line
   }
}

$ exampleplugin some-input

In this case, the value of 'opt' will be "some-input". @Options are described in detail later in this section.

Named commands must, to little surprise, be given a name with which they are invoked. This is done by placing the @Command(name="...") annotation on a public Java method in your Plugin class.

The following command would be executed by executing the plugin by its name, followed by the name of the command:

public class ExamplePlugin implements Plugin {
   @Command(name="perform")
   public void exampleCommand( @Option(required=false) String opt, PipeOut out) {
       out.println(">> the command \"perform\" was invoked with the value: " + opt);
   }
}

$ exampleplugin perform
>> the command "perform" was invoked with the value: null

Notice that our command method has a parameter called "PipeOut," in addition to our 'opt' parameter. PipeOut is a special parameter, which can be placed in any order. It provides access to a variety of shell output functions, including enabling color and controlling piping between plugins.

Along with PipeOut, there is also a @PipeIn InputStream stream annotation, which is used to inject a piped input stream (output from another Plugin's PipeOut.) These concepts will be described more in the section on piping, but for now, you should just know that PipeOut is used to write output to the Forge console.

As mentioned above, options can be given both a long-name and/or a short-name. in which case, they would be defined like this:

@Option(name="one", shortName="o")

Short named parameters are called using a single dash '-' followed by the letter assigned '-o'; whereas long-named parameters are called using a double dash '--' immediately followed by the name '--one'. )

For example, the following command accepts several options, named 'one', and 'two':

public class ExamplePlugin implements Plugin {
   @Command(name="perform")
   public void exampleCommand( 
                  @Option(name="one", shortName="o") String one,
                  @Option(name="two") String two,
                  PipeOut out) {
       out.println(">> option one equals: " + one);
       out.println(">> option two equals: " + two);
   }
}

The above command, when executed, would produce the following output:

$ example-plugin perform --one cat --two dog 
>> option one equals: cat
>> option two equals: dog

$ example-plugin perform --one cat --two dog
$ example-plugin perform --two dog --one cat
$ example-plugin perform --two dog -o cat

In addition to --named option parameters, as described above, parameters may also be passed on the command line by the order in which they are entered. These are called "ordered option parameters", and do not require any parameters other than help or description information.

@Option String value

The order of the options in the method signature controls how values are assigned from parsed Forge shell command statements.

For example, the following command accepts several options, named 'one', and 'two':

public class ExamplePlugin implements Plugin {
   @Command(name="perform")
   public void exampleCommand( 
                  @Option String one,
                  @Option String two,
                  PipeOut out) {
       out.println(">> first option equals: " + one);
       out.println(">> second option equals: " + two);
   }
}

The above command, when executed, would produce the following output:

$ example-plugin cat dog 
>> option one equals: cat
>> option two equals: dog

Both --named and ordered option parameters can be mixed in the same command; there are some constraints on how commands must be typed, but there is a great deal of flexibility as well.

@Option String value,
@Option(name="num") int number

The order of ordered options in the method signature controls how values are assigned from the command line shell, whereas the named options have no bearing on the order in which inputs are provided on the command line.

For example, the following command accepts several options, named 'one', 'two', and several more options that are not named:

public class ExamplePlugin implements Plugin {
   @Command(name="perform")
   public void exampleCommand( 
                  @Option(name="one") String one,
                  @Option(name="two") String two,
                  @Option String three,
                  @Option String four,
                  PipeOut out) {
       out.println(">> first option equals: " + one);
       out.println(">> second option equals: " + two);
       out.println(">> third option equals: " + three);
       out.println(">> fourth option equals: " + four);
   }
}

The above command, when executed, would produce the following output:

$ example-plugin --one cat --two dog bird lizard  
>> option one equals: cat
>> option two equals: dog 
>> option one equals: bird
>> option two equals: lizard

However, we could also achieve the same result by re-arranging parameters, and as long as the name-value pairs remain together, and the ordered values are passed in the correct order, interpretation will remain the same:

$ example-plugin --two dog bird --one cat lizard  
>> option one equals: cat
>> option two equals: dog 
>> option one equals: bird
>> option two equals: lizard

This table describes all of the available @Option(...) attributes and their usage.

@Option(name="exampleName")

@Option(required="false")

Inital field values can be set three different ways as shown below:

<r:MyBean company="Red Hat Inc" />



<r:MyBean>

  <r:company>Red Hat Inc</r:company>

</r:MyBean>



<r:MyBean>

  <r:company>

    <s:value>Red Hat Inc<s:value>

    <r:SomeQualifier/>

  </r:company>

</r:MyBean>

The third form is the only one that also allows you to add annotations such as qualifiers to the field.

It is possible to set Map,Array and Collection field values. Some examples:

<my:ArrayFieldValue>



    <my:intArrayField>

        <s:value>1</s:value>

        <s:value>2</s:value>

    </my:intArrayField>

    

    <my:classArrayField>

        <s:value>java.lang.Integer</s:value>

        <s:value>java.lang.Long</s:value>

    </my:classArrayField>

    

    <my:stringArrayField>

        <s:value>hello</s:value>

        <s:value>world</s:value>

    </my:stringArrayField>

    

</my:ArrayFieldValue>



<my:MapFieldValue>



    <my:map1>

        <s:entry><s:key>1</s:key><s:value>hello</s:value></s:entry>

        <s:entry><s:key>2</s:key><s:value>world</s:value></s:entry>

    </my:map1>

    

    <my:map2>

        <s:e><s:k>1</s:k><s:v>java.lang.Integer</s:v></s:e>

        <s:e><s:k>2</s:k><s:v>java.lang.Long</s:v></s:e>

    </my:map2>

    

</my:MapFieldValue>

Type conversion is done automatically for all primitives and primitive wrappers, Date, Calendar,Enum and Class fields.

The use of EL to set field values is also supported:

<m:Report>

   <m:name>#{reportName}</m:name>

   <m:parameters>

      <s:key>#{paramName}</s:key>

      <s:value>#{paramValue}</s:key>

   </m:parameters>

</m:Report>

Internally field values are set by wrapping the InjectionTarget for a bean. This means that the expressions are evaluated once, at bean creation time.

Inline beans allow you to set field values to another bean that is declared inline inside the field declaration. This allows for the configuration of complex types with nestled classes. Inline beans can be declared inside both <s:value> and <s:key> elements, and may be used in both collections and simple field values. Inline beans must not have any qualifier annotations declared on the bean, instead Seam Config assigns them an artificial qualifier. Inline beans may have any scope, however the default Dependent scope is recommended.

<my:Knight>

  <my:sword>

     <value>

        <my:Sword type="sharp"/>

     </value>

  </my:sword>

  <my:horse>

     <value>

        <my:Horse>

           <my:name>

              <value>billy</value>

           </my:name>

           <my:shoe>

              <Inject/>

           </my:shoe>

        </my:Horse>

     </value>

  </my:horse>

</my:Knight>

In order to enable declarative transaction management for managed beans you need to list the transaction interceptor in beans.xml:

<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://java.sun.com/xml/ns/javaee"

   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

   xsi:schemaLocation="

      http://java.sun.com/xml/ns/javaee

      http://docs.jboss.org/cdi/beans_1_0.xsd">

   <interceptors>

      <class>org.jboss.seam.transaction.TransactionInterceptor</class>

   </interceptors>

</beans>

If you are in a Java EE 6 environment then you are good to go, no additional configuration is required.

If you are not in an EE environment you may need to configure some things with seam-xml. You may need the following entries in your beans.xml file:

<beans xmlns="http://java.sun.com/xml/ns/javaee"

   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

   xmlns:s="urn:java:ee"

   xmlns:t="urn:java:org.jboss.seam.transaction"

   xsi:schemaLocation="

      http://java.sun.com/xml/ns/javaee

      http://docs.jboss.org/cdi/beans_1_0.xsd">



      <t:SeSynchronizations>

         <s:modifies/>

      </t:SeSynchronizations>



      <t:EntityTransaction>

         <s:modifies />

      </t:EntityTransaction>



</beans>

Let's look at these individually.

<t:SeSynchronizations>

  <s:modifies/>

</t:SeSynchronizations>

Seam will attempt to use JTA synchronizations if possible. If not then you need to install the SeSynchronzations bean to allow seam to handle synchronizations manually. Synchronizations allow seam to respond to transaction events such as beforeCompletion() and afterCompletion(), and are needed for the proper operation of the Seam Managed Persistence Context.

<t:EntityTransaction>

   <s:modifies />

</t:EntityTransaction>

By default seam will attempt to look up java:comp/UserTransaction from JNDI (or alternatively retrieve it from the EJBContext if a container managed transaction is active). Installing EntityTransaction tells seam to use the JPA EntityTransaction instead. To use this you must have a Seam Managed Persistence Context installed with qualifier @Default.

If your entity manager is installed with a different qualifier, then you need to use the following configuration (this assumes that my has been bound to the namespace that contains the appropriate qualifier, see the Seam Config XML documentation for more details):

<t:EntityTransaction>

   <s:modifies />

   <t:entityManager>

      <my:SomeQualifier/>

   </tentityManager>

</t:EntityTransaction>

Seam adds declarative transaction support to managed beans. Seam re-uses the EJB @TransactionAttribute for this purpose, however it also provides an alternative @Transactional annotation for environments where the EJB API's are not available. An alternative to @ApplicationException, @SeamApplicationException is also provided. Unlike EJBs, managed beans are not transactional by default, you can change this by adding the @TransactionAttribute to the bean class.

Unlike in Seam 2, transactions will not roll back whenever a non-application exception propagates out of a bean, unless the bean has the transaction intercepter enabled.

If you are using seam managed transactions as part of the seam-faces module you do not need to worry about declarative transaction management. Seam will automatically start a transaction for you at the start of the faces request, and commit it before the render response phase.

Let's have a look at some code. Annotations applied at a method level override annotations applied at the class level.

@TransactionAttribute /*Defaults to TransactionAttributeType.REQUIRED */

class TransactionaBean

{


   /* This is a transactional method, when this method is called a transaction

    * will be started if one does not already exist.

    * This behavior is inherited from the @TransactionAttribute annotation on

    * the class.

    */

    void doWork()

    {

      ...

    }


    /* A transaction will not be started for this method, however it      */

    /* will not complain if there is an existing transaction active.      */

    @TransactionAttributeType(TransactionAttributeType.SUPPORTED)

    void doMoreWork()

    {

      ...

    }


    /* This method will throw an exception if there is no transaction active when */

    /* it is invoked.                                                             */


    @TransactionAttributeType(TransactionAttributeType.MANDATORY)

    void doEvenMoreWork()

    {

      ...

    }


    /* This method will throw an exception if there is a transaction active when */

    /* it is invoked.                                                            */

    @TransactionAttributeType(TransactionAttributeType.NOT_SUPPORTED)

    void doOtherWork()

    {

      ...

    }

}         

@SeamManaged
@Produces
@PersistenceUnit
@ConversationScoped
EntityManagerFactory producerField;
         

This is just an ordinary resource producer field as defined by the CDI specification, however the presence of the @SeamManaged annotation tells seam to create a seam managed persistence context from this EntityManagerFactory. This managed persistence context can be injected normally, and has the same scope and qualifiers that are specified on the resource producer field.

This will work even in a SE environment where @PersistenceUnit injection is not normally supported. This is because the seam persistence extensions will bootstrap the EntityManagerFactory for you.

Now we can have our EntityManager injected using:

@Inject EntityManager entityManager;

Persistence contexts scoped to the conversation allows you to program optimistic transactions that span multiple requests to the server without the need to use the merge() operation , without the need to re-load data at the beginning of each request, and without the need to wrestle with the LazyInitializationException or NonUniqueObjectException.

As with any optimistic transaction management, transaction isolation and consistency can be achieved via use of optimistic locking. Fortunately, both Hibernate and EJB 3.1 make it very easy to use optimistic locking, by providing the @Version annotation.

By default, the persistence context is flushed (synchronized with the database) at the end of each transaction. This is sometimes the desired behavior. But very often, we would prefer that all changes are held in memory and only written to the database when the conversation ends successfully. This allows for truly atomic conversations. Unfortunately there is currently no simple, usable and portable way to implement atomic conversations using EJB 3.1 persistence. However, Hibernate provides this feature as a vendor extension to the FlushModeTypes defined by the specification, and it is our expectation that other vendors will soon provide a similar extension.

Seam proxies the EntityManager or Session object whenever you use a Seam-managed persistence context. This lets you use EL expressions in your query strings, safely and efficiently. For example, this:

User user = em.createQuery("from User where username=#{user.username}")

   .getSingleResult();

is equivalent to:

User user = em.createQuery("from User where username=:username")

   .setParameter("username", user.getUsername())

   .getSingleResult();

Of course, you should never, ever write it like this:

User user = em.createQuery("from User where username=" + user.getUsername()) //BAD!

   .getSingleResult();

(It is inefficient and vulnerable to SQL injection attacks.)

Sometimes you may want to perform some additional setup on the EntityManager after it has been created. For example, if you are using Hibernate you may want to set a filter. Seam persistence fires a SeamManagedPersistenceContextCreated event when a Seam managed persistence context is created. You can observe this event and perform any setup you require in an observer method. For example:

public void setupEntityManager(@Observes SeamManagedPersistenceContextCreated event) {

   Session session = (Session)event.getEntityManager().getDelegate();

   session.enableFilter("myfilter");

}

Authentication is the act of establishing, or confirming, the identity of a user. In many applications a user confirms their identity by providing a username and password (also known as their credentials). Seam Security allows the developer to control how users are authenticated, by providing a flexible Authentication API that can be easily configured to allow authentication against any number of sources, including but not limited to databases, LDAP directory servers or some other external authentication service.

If none of the built-in authentication providers are suitable for your application, then it is also possible to write your own custom Authenticator implementation.

Identity Management is a set of useful APIs for managing the users, groups and roles within your application. The identity management features in Seam are provided by PicketLink IDM, and allow you to manage users stored in a variety of backend security stores, such as in a database or LDAP directory.

Seam Security contains an external authentication sub-module that provides a number of features for authenticating your application users against external authentication services, such as OpenID and SAML.

While authentication is used to confirm the identity of the user, authorization is used to control which actions a user may perform within your application. Authorization can be roughly divided into two categories; coarse-grained and fine-grained. An example of a coarse-grained restriction is allowing only members of a certain group or role to perform a privileged operation. A fine-grained restriction on the other hand may allow only a certain individual user to perform a specific action on a specific object within your application.

There are also rule-based permissions, which bridge the gap between fine-grained and coarse-grained restrictions. These permissions may be used to determine a user's privileges based on certain business logic.

The Maven artifacts for all Seam modules are hosted within the JBoss Maven repository. Please refer to the Maven Getting Started Guide for information about configuring your Maven installation to use the JBoss repository.

To use Seam Security within your Maven-based project, it is advised that you import the Seam BOM (Bill of Materials) which declares the versions for all Seam modules. First declare a property value for ${seam.version} as follows:

<properties>

  <seam.version>3.0.0.Final</seam.version>

</properties>

You can check the JBoss Maven Repository directly to determine the latest version of the Seam BOM to use.

Now add the following lines to the list of dependencies within the dependencyManagement section of your project's pom.xml file:

<dependency>

  <groupId>org.jboss.seam</groupId>

  <artifactId>seam-bom</artifactId>

  <version>${seam.version}</version>

  <type>pom</type>

  <scope>import</scope>

</dependency>