Follow these steps to install a Forge distribution:

That's it, you've now got Forge installed, but what to do next?

There are a few things you should probably check-out. If you are confused at any time, try pressing <TAB>. For instance, if you have not yet seen the Forge built-in commands, you may either press <TAB> to see a list of the currently available commands, or get a more descriptive list by typing:

$ list-commands --all

You may also use the 'help' command for more detailed information about available Forge, a plugin, or a command.

$ help {plugin-name} {command-name}

Assuming you have already completed the steps to install Forge, the first thing you'll need to do is download and install JBoss Application Server 6.0 or 7.0. This server will host your application once it is built.

Next, follow these steps to create your skeleton web-application; be sure to replace any {ARGS} with your own personal values. Also keep in mind that while typing commands, you may press <TAB> at any time to see command completion options:

Because Forge is based on Maven, the easiest way to get started quickly writing a plugin is to create a new maven Java project. This can be done by hand, or using Forge's build in plugin project facet.

[no project] Desktop $
[no project] Desktop $ new-project --named example-plugin --topLevelPackage com.example.forge.plugin
Use [~/Desktop/example-plugin] as project directory? [Y/n] Y
Wrote ~/Desktop/example-plugin/src/main/resources/META-INF/forge.xml
***SUCCESS*** Created project [example-plugin] in new working directory [~/Desktop/example-plugin]
[example-plugin] example-plugin $
[example-plugin] example-plugin $ 
[example-plugin] example-plugin $ project install-facet forge.api
The [forge.api] facet depends on the following missing facet(s): [forge.spec.cdi]. Install as well? [Y/n] Y
Wrote ~/Desktop/example-plugin/src/main/resources/META-INF/beans.xml
***SUCCESS*** Installed [forge.spec.cdi] successfully.
Install which version of the Forge API?

  1 - [org.jboss.seam.forge:forge-shell-api:1.0.0-SNAPSHOT]
  2 - [org.jboss.seam.forge:forge-shell-api:1.0.0.Alpha2]

Choose an option by typing the number of the selection: 1
***SUCCESS*** Installed [forge.api] successfully.
[example-plugin] example-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>

The first thing you must do in order to create a forge plugin, is create a new class and implement the org.jboss.seam.forge.shell.plugins.Plugin interface. Notice that the interface has no methods, this is because you will be adding your own custom commands later.

import org.jboss.seam.forge.shell.plugins.Plugin;
         
public class ExamplePlugin implements Plugin {
}

Now that you have implemented the Plugin interface, it's time to add some functionality. This is done by adding "Commands" to your plugin class. Commands are plain Java methods in your plugin Class. Plugin methods must be annotated as either a @DefaultCommand, the method to be invoked if the plugin is called by name (with no additional commands), or @Command(name="..."), in which case the plugin name and command name must both be used to invoke the method.

Commands also accept @Options parameters as arguments. These are described in detail later in this section.

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

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

Once we have a command or two in our Plugin, it's time to give our users some control over what it does; to do this, we use @Option params; options enable users to pass information of various types into our commands.

Options can be named, in which case they are set by passing the --name followed immediately by the value, or if the option is a boolean flag, simply passing the flag will signal a `true` value. Named parameters may be passed into a command in any order, while unnamed parameters must be passed into the command in the order with which they were defined.

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

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);
   }
}

$ 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

@Option String value

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

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

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

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(">> option one equals: " + one);
       out.println(">> option two equals: " + two);
       out.println(">> option three equals: " + three);
       out.println(">> option four equals: " + four);
   }
}

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

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

Much like a standard UNIX-style shell, the Forge shell supports piping IO between executables; however in the case of forge, piping actually occurs between plugins, commands, for example:

$ cat /home/username/.forge/config | grep automatic 
@/* Automatically generated config file */;

This might look like a typical BASH command, but if you run forge and try it, you may be surprised to find that the results are the same as on your system command prompt, and in this example, we are demonstrating the pipe: '|'

In order to enable piping in your plugins, you must use one or both of the @PipeIn InputStream stream or PipeOut out command arguments. Notice that PipeOut is a java type that must be used as a Method parameter, whereas @PipeIn is an annotation that must be placed on a Java @PipeIn InputStream stream or @PipeIn String in Method parameter.

`PipeOut out` - by default - is used to print output to the shell console; however, if the plugin on the left-hand-side is piped to a secondary plugin on the command line, the output will be written to the `@PipeIn InputStream stream` of the plugin on the right-hand-side:

$ left | right

Or in terms of pipes, this could be thought of as a flow of data from left to right:

$ PipeOut out -> @PipeIn InputStream stream

Notice that you can pipe output between any number of plugins as long as each uses both a @PipeIn InputStream and PipeOut:

$ first command | second command | third command

   @Command("example-command")
   public void exampleCommand(
            @PipeIn final InputStream in,
            @Option(required = false) final boolean option,
            PipeOut out)
   { ... }

   @Command("example-command")
   public void exampleCommand(
            @PipeIn final String in,
            @Option(required = false) final boolean option,
            PipeOut out)
   { ... }

@Alias("grep")
@Topic("File & Resources")
@Help("print lines matching a pattern")
public class GrepPlugin implements Plugin
{
   @DefaultCommand
   public void run(
         @PipeIn final InputStream pipeIn,
         @Option(name = "ignore-case", shortName = "i", flagOnly = true) boolean ignoreCase,
         @Option(name = "regexp", shortName = "e") String regExp,
         @Option(description = "PATTERN") String pattern,
         @Option(description = "FILE ...") Resource<?>[] resources, 
         final PipeOut pipeOut
   ) throws IOException 
   {
      Pattern matchPattern = /* determine pattern (omitted for space) */;

      if (resources != null) {
      
         /* User passed file(s) on the command line; grep those. */
      
         for (Resource<?> r : resources) {
            InputStream inputStream = r.getResourceInputStream();
            try {
               match(inputStream, matchPattern, pipeOut, ignoreCase);
            }
            finally {
               inputStream.close();
            }
         }
      }
      else if (pipeIn != null) {
      
         /* No files were passed on the command line; check for a 
          * piped InputStream and use that.
          */
      
         match(pipeIn, matchPattern, pipeOut, ignoreCase);
      }
      else {
      
         /* No input was passed to the plugin. */
      
         throw new RuntimeException("Error: arguments required");
      }
   }

   private void match(InputStream instream, Pattern pattern, PipeOut pipeOut, boolean caseInsensitive) throws IOException {
      StringAppender buf = new StringAppender();

      int c;
      while ((c = instream.read()) != -1) { /* Read from the given stream. */
         switch (c) {
         case '\r':
         case '\n':
            String s = caseInsensitive ? buf.toString().toLowerCase() : buf.toString();

            if (pattern.matcher(s).matches()) {
               pipeOut.println(s); /* Write to the output pipe. */
            }
            buf.reset();
            break;
         default:
            buf.append((char) c);
            break;
         }
      }
   }
}

If your Plugin depends on classes or libraries that are not provided by Forge, then you must either package those classes in the JAR file containing your Plugin (for instance, using the maven shade plugin), or you must ensure that the required dependencies are also placed on the CLASSPATH (typically in the $FORGE_HOME/lib folder,) otherwise your plugin will *not* be loaded.

[example-plugin] example-plugin $ shade setup
***SUCCESS*** Shade plugin is installed.
[example-plugin] example-plugin $              
[example-plugin] example-plugin $ shade include commons-collections:commons-collections:3.2.1

      <plugin>
        <artifactId>maven-shade-plugin</artifactId>
        <version>1.4</version>
        <executions>
          <execution>
            <phase>package</phase>
            <goals>
              <goal>shade</goal>
            </goals>
            <configuration>
              <artifactSet>
                <includes>
                  <include>commons-collections:commons-collections</include>
                </includes>
              </artifactSet>
            </configuration>
          </execution>
        </executions>
      </plugin>
		

$ shade relocate --pattern {ORIGINAL PGK} --shadedPattern {NEW PKG} --excludes {EXCLUDED PKGS...}

[example-plugin] example-plugin $ shade relocate --pattern org.apache.commons.collections --shadedPattern ~.shaded.apache.collections
***SUCCESS*** Relocating [org.apache.commons.collections] to [com.example.forge.plugin.shaded.apache.collections]
[example-plugin] example-plugin $ 
      	

   <plugin>
     <artifactId>maven-shade-plugin</artifactId>
     <version>1.4</version>
     <executions>
       <execution>
         <phase>package</phase>
         <goals>
           <goal>shade</goal>
         </goals>
         <configuration>
           <relocations>
             <relocation>
               <pattern>org.apache.commons.collections</pattern>
               <shadedPattern>com.example.forge.plugin.shaded.apache.collections</shadedPattern>
             </relocation>
           </relocations>
         </configuration>
       </execution>
     </executions>
   </plugin>

After following all of the steps in this section, you should now be ready to install your Plugin into the Forge environment. There are several methods for installing and distributing your plugin; these methods are described in this section.

All plugin installation should take place using the '$ forge' meta-command. For more information on this command, type:

$ help forge

$ forge source-plugin {PATH}

If you are using Maven as your build tool, first make sure you have configured your build to use the JBoss Community repository, where you can find all the Seam artifacts. Then, add the following single dependency to your pom.xml file to get started using Seam Solder:

<dependency>

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

   <artifactId>seam-solder</artifactId>

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

</dependency>

This artifact includes the combined API and implementation.

To be more strict, you can use the API at compile time and only include the implementation at runtime. This protects you from inadvertantly depending on an implementation class.

<dependency>

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

   <artifactId>seam-solder-api</artifactId>

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

   <scope>compile</scope>

</dependency>



<dependency>

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

   <artifactId>seam-solder-impl</artifactId>

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

   <scope>runtime</scope>

</dependency>

In a Servlet 3.0 or Java EE 6 environment, your configuration is now complete!

Most of Seam Solder has very few dependencies, only one of which is not provided by Java EE 6:

<dependency>

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

   <artifactId>seam-solder-parent</artifactId>

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

   <type>pom</type>

   <scope>import</scope>

</dependency>

Some features of Seam Solder require additional dependencies (which are declared optional, so will not be added as transitive dependencies):

If you are using Java EE 5 or some other Servlet 2.5 container, then you need to manually register a Servlet component in your application's web.xml to access resources from the Servlet Context.

<listener>

   <listener-class>org.jboss.seam.solder.resourceLoader.servlet.ResourceListener</listener-class>

</listener>

This registration happens automatically in a Servlet 3.0 environment through the use of a /META-INF/web-fragment.xml included in the Solder implementation.

Annotating an injection point with @Exact allows you to select an exact implementation of the injection point type to inject. For example:

interface PaymentService { 

   ...

}

class ChequePaymentService implements PaymentService { 

   ...

}

class CardPaymentService implements PaymentService { 

   ...

}

class PaymentProcessor { 

   

   @Inject @Exact(CardPaymentService.class)

   PaymentService paymentService;

   

   ...

   

}

It is common to want to qualify a bean as belonging to the current client (for example we want to differentiate the default system locale from the current client's locale). Seam Solder provides a built in qualifier, @Client for this purpose.

Seam Solder allows you to annotate the package @Named, which causes every bean defined in the package to be given its default name. Package annotations are defined in the file package-info.java. For example, to cause any beans defined in com.acme to be given their default name:

@Named

package com.acme

According to the CDI standard, the @Named annotation assigns a name to a bean equal to the value specified in the @Named annotation or, if a value is not provided, the simple name of the bean class. This behavior aligns is with the needs of most application developers. However, framework writers should avoid trampling on the "root" bean namespace. Instead, frameworks should specify qualified names for built-in components. The motivation is the same as qualifying Java types. The @FullyQualified provides this facility without sacrificing type-safety.

Seam Solder allows you to customize the bean name using the complementary @FullyQualified annotation. When the @FullyQualified annotation is added to a @Named bean type, producer method or producer field, the standard bean name is prefixed with the name of the Java package in which the bean resides, the segments separated by a period. The resulting fully-qualified bean name (FQBN) replaces the standard bean name.

package com.acme;

      

@FullyQualified @Named

public class NamedBean {

   public String getAge()

   {

      return 5;

   }

}

The bean in the previous code listing is assigned the name com.acme.namedBean. The value of its property age would be referenced in an EL expression (perhaps in a JSF view template) as follows:

#{com.acme.namedBean.age}

The @FullyQualified annotation is permitted on a bean type, producer method or producer field. It can also be used on a Java package, in which case all @Named beans in that package get a bean name which is fully-qualified.

@FullyQualified

package com.acme;

If you want to use a different Java package as the namespace of the bean, rather than the Java package of the bean, you specify any class in that alternative package in the annotation value.

package com.acme;

      

@FullyQualified(ClassInOtherPackage.class) @Named

public class CustomNamespacedNamedBean {

   ...

}

If you want to load resources from another location, you can provide an additional resource loader. First, create the resource loader implementation:

class MyResourceLoader implements ResourceLoader {

   ...

}

And then register it as a service by placing the fully qualified class name of the implementation in a file called META-INF/services/org.jboss.seam.solder.resourceLoader.ResourceLoader.

Before talking about Solder Logging, you need to first be introduced to JBoss Logging 3. The reason is, JBoss Logging provides the foundation on which Solder's declarative programming model for logging is built. Plus, we have to convince you that you aren't tied to JBoss AS by using it.

JBoss Logging acts as a logging bridge. If you don't add any other logging libraries to your project, it will delegate all logging calls it handles to the logging facility built into the Java platform (commonly referred to as JDK logging). That's nice, because it means your deployment headaches caused by missing logging jars are gone. And you accomplish it all through the use of the Logger type. It has the usual level-based log methods and complimentary ones that provide formatting.

Here's an example of how you obtain a logger and log a basic message:

Logger log = Logger.getLogger(Bean.class);

// log a plain text method

log.debug("I'm using JBoss Logging.");

If you want to use another logging engine, such as SLF4J or Log4J, you just have to add the native library to the deployment. Keep in mind, though, if your application server provides one of these frameworks, it will get choosen instead. On JBoss AS, JBoss Logging will prefer the JBoss LogManager because it's the built-in logging engine. (We are looking into more sophisticated runtime selection of the logging engine).

Here are the providers JBoss Logging supports (and the order in which it looks for them):

So you get that JBoss Logging is an abtraction. What else is it good for?

JBoss Logging has a facility for formatting log messages, using either the printf syntax or MessageFormat. This makes it possible to use positional parameters to build dynamic log messages based on contextual information.

Logger log = Logger.getLogger(Bean.class);

// log a message formatted using printf-style substitutions

log.infof("My name is %s.", "David");

// log a message formatted using MessageFormat-style substitutions

log.errorv("The license for Seam is the {0}", "APL");

The most significant and distinguishing feature of JBoss Logging is support for typed loggers. A typed logger is an interface that defines methods which serve as logging operations. When a method is invoked on one of these interfaces, the message defined in an annotation on the method is interpolated and written to the underlying logging engine.

Here's an example of a typed logger:

import org.jboss.logging.Message;

import org.jboss.logging.LogMessage;

import org.jboss.logging.MessageLogger;


@MessageLogger

public interface CelebritySightingLog {


    @LogMessage @Message("Spotted celebrity %s!") 

    void spottedCelebrity(String name);


}

JBoss Logging has is parallel support for typed message bundles, whose methods return a formatted message rather than log it. Combined, these features form the centerpiece of Solder's logging and message bundle programming model (and a foundation for additional support provided by the Seam international module). After looking at the samples provided so far, don't pull out your IDE just yet. We'll get into the details of typed loggers and how to use them in Solder in a later section.

There you have it! JBoss Logging is a low-level API that provides logging abstraction, message formatting and internationalization, and typed loggers. But it doesn't tie you to JBoss AS!

With that understanding, we'll now move on to what Solder does to turn this foundation into a programming model and how to use it in your CDI-based application.

Solder builds on JBoss Logging 3 to provide the following feature set:

Without further discussion, let's get into it.

To define a typed logger, first create an interface, annotated it, then add methods that will act as log operations and configure the message it will print using another annotation:

import org.jboss.seam.solder.messages.Message;

import org.jboss.seam.solder.logging.Log;

import org.jboss.seam.solder.logging.MessageLogger;

      

@MessageLogger

public interface TrainSpotterLog {


    @Log @Message("Spotted %s diesel trains") 

    void dieselTrainsSpotted(int number);


}

We have configured the log messages to use printf-style interpolations of parameters (%s).

You can then inject the typed logger with no further configuration necessary. We use another optional annotation to set the category of the logger to "trains" at the injection point, overriding the default category of the fully-qualified class name of the component receiving the injection:

    @Inject @Category("trains")

    private TrainSpotterLog log;

We log a message by simply invoking a method of the typed logger interface:

   log.dieselTrainsSpotted(7);

The default locale will be used unless overridden. Here we configure the logger to use the UK locale:

    @Inject @Category("trains") @Locale("en_GB")

    private TrainSpotterLog log;

You can also log exceptions.

import org.jboss.seam.solder.messages.Message;

import org.jboss.seam.solder.messages.Cause;

import org.jboss.seam.solder.logging.Log;

import org.jboss.seam.solder.logging.MessageLogger;


@MessageLogger

public interface TrainSpotterLog {


    @Log @Message("Failed to spot train %s") 

    void missedTrain(String trainNumber, @Cause Exception exception);


}

You can then log a message with an exception as follows:

try {

    ...

} catch (Exception e) {

    log.missedTrain("RH1", e);

}

The stacktrace of the exception parameter will be written to the log along with the message.

Typed loggers also provide internationalization support. Simply add the @MessageBundle annotation to the logger interface.

If injecting a typed logger seems to "enterprisy" to you, or you need to get a reference to it from outside of CDI, you can use a static accessor method on Logger:

TrainSpotterLog log = Logger.getMessageLogger(TrainSpotterLog.class, "trains");

log.dieselTrainsSpotted(7);

The injected version is a convenience for those who prefer the declarative style of programming. If you are looking for a simpler starting point, you can simply use the Logger directly.

You can also inject a "plain old" Logger (from the JBoss Logging API):

import javax.inject.Inject;


import org.jboss.logging.Logger;


public class LogService {

    @Inject

    private Logger log;


    public void logMessage() {

        log.info("Hey sysadmins!");

    }

}

Log messages created from this Logger will have a category (logger name) equal to the fully-qualified class name of the bean implementation class. You can specify a category explicitly using an annotation.

    @Inject @Category("billing")

    private Logger log;

You can also specify a category using a reference to a type:

    @Inject @TypedCategory(BillingService.class)

    private Logger log;

Often times you need to access a localized message. For example, you need to localize an exception message. Seam Solder let's you retrieve this message from a typed message logger to avoid having to use hard-coded string messages.

To define a typed message bundle, first create an interface, annotated it, then add methods that will act as message retrievers and configure the message to produce using another annotation:

import org.jboss.seam.solder.messages.Message;

import org.jboss.seam.solder.messages.MessageBundle;

   

@MessageBundle

public interface TrainMessages {


    @Message("No trains spotted due to %s") 

    String noTrainsSpotted(String cause);


}

Inject it:

    @Inject @MessageBundle

    private TrainMessages messages;

And use it:

   throw new BadDayException(messages.noTrainsSpotted("leaves on the line"));

You may have noticed that throughout this chapter, we've only defined interfaces. Yet, we are injecting and invoking them as though they are concrete classes. So where's the implementation?

Good news. The typed logger and message bundle implementations are generated automatically! You'll see this strategy used often in Seam 3. It's declarative programming at its finest (or to an extreme, depending on how you look at it). Either way, it saves you from a whole bunch of typing.

So how are they generated? Let's find out!

<dependencies>

    <!-- Annotation processor for generating typed logger and message bundle classes -->

    <dependency>

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

        <artifactId>seam-solder-tooling</artifactId>

        <scope>provided</scope>

        <optional>true</optional>

    </dependency>

    ...

</dependencies>

<build>

    <plugins>

        <plugin>

            <groupId>org.apache.maven.plugins</groupId>

            <artifactId>maven-compiler-plugin</artifactId>

            <configuration>

                <source>1.6</source>

                <target>1.6</target>

            </configuration>

        </plugin>

    </plugins>

</build>

TrainSpotterLog_$logger.java
TrainSpotterLog_$logger_en_GB.java
TrainMessages_$bundle.java

TrainMessages_fr.properties

noTrainsSpotted=pas de trains repéré en raison de %s

TrainMessages_$bundle_fr.java

Invalid bundle interface org.example.log.AppLog (implementation not found)

ShrinkWrap.create(JavaArchive.class, "test.jar")
        .addPackage(AppLog.class.getPackage());

Seam Solder provides an AnnotatedType implementation that should be suitable for the needs of most portable extensions. The AnnotatedType is created from AnnotatedTypeBuilder, typically in an extension's observer method, as follows:

AnnotatedTypeBuilder builder = new AnnotatedTypeBuilder()

        .readFromType(type, true) /* readFromType can read from an AnnotatedType or a class */

        .addToClass(ModelLiteral.INSTANCE); /* add the @Model annotation */

Here we create a new builder, and initialize it using an existing AnnotatedType. We can then add or remove annotations from the class, and its members. When we have finished modifying the type, we call create() to spit out a new, immutable, AnnotatedType.

AnnotatedType redefinedType = builder.create();

One place this is immensely useful is for replacing the AnnotatedType in an extension that observes the ProcessAnnotatedType event:

public <X> void processAnnotatedType(@Observes ProcessAnnotatedType<X> evt) {

    AnnotatedTypeBuilder builder = new AnnotatedTypeBuilder()

            .readFromType(evt.getAnnotatedType(), true)

            .addToClass(ModelLiteral.INSTANCE);

    evt.setAnnotatedType(builder.create());

}

This type is now effectively annotated with @Model, even if the annotation is not present on the class definition in the Java source file.

AnnotatedTypeBuilder also allows you to specify a "redefinition", which can be applied to the type, a type of member, or all members. The redefiner will receive a callback for any annotations present which match the annotation type for which the redefinition is applied.

For example, to remove the qualifier @Unique from the type and any of its members, use this:

AnnotatedTypeBuilder builder = new AnnotatedTypeBuilder()

        .readFromType(type, true)

        .redefine(Unique.class, new AnnotationRedefiner<Unique>() {


            public void redefine(RedefinitionContext<A> ctx) {

                ctx.getAnnotationBuilder().remove(Unique.class);

            }


        });

AnnotatedType redefinedType = builder.create();

No doubt, this is a key blade in Solder's army knife arsenal of tools. You can quite effectively change the picture of the type metadata CDI discovers when it scans and processes the classpath of a bean archive.

Sometimes you may need an annotation instance for an annotation whose type is not known at development time. Seam Solder provides a AnnotationInstanceProvider class that can create an AnnotationLiteral instance for any annotation at runtime. Annotation attributes are passed in via a Map<String,Object>. For example given the follow annotation:

@Retention(RetentionPolicy.RUNTIME)

public @interface MultipleMembers {

    int intMember();


    long longMember();


    short shortMember();


    float floatMember();


    double doubleMember();


    byte byteMember();


    char charMember();


    boolean booleanMember();


    int[] intArrayMember();

}

We can create an annotation instance as follows:

/* Create a new provider */

AnnotationInstanceProvider provider = new AnnotationInstanceProvider();


/* Set the value for each of attributes */

Map<String, Object> values = new HashMap<String, Object>();

values.put("intMember", 1);

values.put("longMember", 1);

values.put("shortMember", 1);

values.put("floatMember", 0);

values.put("doubleMember", 0);

values.put("byteMember", ((byte) 1));

values.put("charMember", 'c');

values.put("booleanMember", true);

values.put("intArrayMember", new int[] { 0, 1 });


/* Generate the instance */

MultipleMembers an = provider.get(MultipleMembers.class, values);

The Annotation Inspector allows you to easily discover annotations which are meta-annotated. For example:

/* Discover all annotations on type which are meta-annotated @Constraint */

Set<Annotation> constraints = AnnotationInspector.getAnnotations(type, Constraint.class, beanManager);


/* Load the annotation instance for @FacesValidator the annotation may declared on the type, */

/* or, if the type has any stereotypes, on the stereotypes */

FacesValidator validator = AnnotationInspector.getAnnotation(

        type, FacesValidator.class, true, beanManager);

The utility methods work correctly on Stereotypes as well. Let's say you're working with a bean that was decorated @Model, running the following example will still show you the underlying @Named

// assuming you have a class..

@Model

public class User {

    ...

}


// Assume type represents the User class

assert AnnotationInspector.isAnnotationPresent(type, Named.class, beanManager);


// Retrieves the underlying @Named instance on the stereotype

Named name = AnnotationInspector.getAnnotation(type, Named.class, true, beanManager);

The search algorithm will first check to see if the annotation is present directly on the annotated element first, then searches within the stereotype annotations on the element. If you only want to search for Annotations on Stereotypes, then you can use either of the methods AnnotationInspector.getAnnotationFromStereotype.

There is an overloaded form of isAnnotationPresent and getAnnotation to control whether it will search on Stereotypes or not. For both of these methods, a search is performed first directly on the element before searching in stereotypes.

When developing an extension to CDI, it can be useful to detect certain injection points, or bean definitions and based on annotations or other metadata, add qualifiers to further disambiguate the injection point or bean definition for the CDI bean resolver. Solder's synthetic qualifers can be used to easily generate and track such qualifers.

In this example, we will create a synthetic qualifier provider, and use it to create a qualifier. The provider will track the qualifier, and if a qualifier is requested again for the same original annotation, the same instance will be returned.

/* Create a provider, giving it a unique namespace */

Synthetic.Provider provider = new Synthetic.Provider("com.acme");


/* Get the a synthetic qualifier for the original annotation instance */

Synthetic synthetic = provider.get(originalAnnotation);


/* Later calls with the same original annotation instance will return the same instance */

/* Alternatively, we can "get and forget" */


Synthetic synthetic2 = provider.get();

Seam Solder comes with a number miscellaneous reflection utilities; these extend JDK reflection, and some also work on CDI's Annotated metadata. See the javadoc on Reflections for more.

Solder also includes a simple utility, PrimitiveTypes for converting between primitive and their respective wrapper types, which may be useful when performing data type conversion. Sadly, this is functionality which is missing from the JDK.

InjectableMethod allows an AnnotatedMethod to be injected with parameter values obtained by following the CDI type safe resolution rules, as well as allowing the default parameter values to be overridden.

The Property<V> interface declares a number of methods for interacting with bean properties. You can use these methods to read or set the property value, and read the property type information. Properties may be readonly.

class Person {

   

   PersonName personName;

   

   Address address;

   

   void setPostcode(String postcode) {

      address.setPostcode(postcode);

   }

   

   String getPostcode() {

      return address.getPostcode();

   }

   

}

   Property<PersonName> personNameProperty = Properties.createProperty(Person.class.getField("personName");

   Property<String> postcodeProperty = Properties.createProperty(Person.class.getMethod("getPostcode"));

To create a property query, use the PropertyQueries class to create a new PropertyQuery instance:

   PropertyQuery<?> query = PropertyQueries.createQuery(Foo.class);

If you know the type of the property that you are querying for, you can specify it via a type parameter:

   PropertyQuery<String> query = PropertyQueries.<String>createQuery(identityClass);

Once you have created the PropertyQuery instance, you can add search criteria. Seam Solder provides three built-in criteria types, and it is very easy to add your own. A criteria is added to a query via the addCriteria() method. This method returns an instance of the PropertyQuery, so multiple addCriteria() invocations can be stacked.

   public class Foo {  
      private String accountNumber;
      private @Scrambled String accountPassword;    
      private String accountName;    
   }

   PropertyQuery<String> query = PropertyQueries.<String>createQuery(Foo.class)
      .addCriteria(new AnnotatedPropertyCriteria(Scrambled.class));

public class Foo {
   public String getBar() {
      return "foobar";
   }
}

   PropertyQuery<String> query = PropertyQueries.<String>createQuery(Foo.class)
      .addCriteria(new NamedPropertyCriteria("bar"));

public class Foo {
   private Bar bar;
}

PropertyQuery<Bar> query = PropertyQueries.<Bar>createQuery(Foo.class)
      .addCriteria(new TypedPropertyCriteria(Bar.class));

public class WholeNumberPropertyCriteria implements PropertyCriteria {
   public boolean fieldMatches(Field f) {
      return f.getType() == Integer.class || f.getType() == Integer.TYPE.class ||
             f.getType() == Long.class || f.getType() == Long.TYPE.class ||
             f.getType() == BigInteger.class;
   }   

   boolean methodMatches(Method m) {
      return m.getReturnType() == Integer.class || m.getReturnType() == Integer.TYPE.class ||
             m.getReturnType() == Long.class || m.getReturnType() == Long.TYPE.class ||
             m.getReturnType() == BigInteger.class;
   }
}

After creating the PropertyQuery and setting the criteria, the query can be executed by invoking either the getResultList() or getFirstResult() methods. The getResultList() method returns a List of Property objects, one for each matching property found that matches all the specified criteria:

   List<Property<String>> results = PropertyQueries.<String>createQuery(Foo.class)
     .addCriteria(TypedPropertyCriteria(String.class))
     .getResultList();

If no matching properties are found, getResultList() will return an empty List. If you know that the query will return exactly one result, you can use the getFirstResult() method instead:

   Property<String> result = PropertyQueries.<String>createQuery(Foo.class)
      .addCriteria(NamedPropertyCriteria("bar"))
      .getFirstResult();

If no properties are found, then getFirstResult() will return null. Alternatively, if more than one result is found, then getFirstResult() will return the first property found.

Alternatively, if you know that the query will return exactly one result, and you want to assert that assumption is true, you can use the getSingleResult() method instead:

   Property<String> result = PropertyQueries.<String>createQuery(Foo.class)
      .addCriteria(NamedPropertyCriteria("bar"))
      .getSingleResult();

If no properties are found, or more than one property is found, then getSingleResult() will throw an exception. Otherwise, getSingleResult() will return the sole property found.

Sometimes you may not be interested in read only properties, so getResultList(),getFirstResult() and getSingleResult() have corresponding getWritableResultList(),getWritableFirstResult() and getWritableSingleResult() methods, that will only return properties that are not read-only. This means that if there is a field and a getter method that resolve to the same property, instead of getting a read-only MethodProperty you will get a writable FieldProperty.

Before we take a look at creating generic beans, let's see how we will use them.

Generic beans are configured via producer methods and fields. We want to create two queues to interact with ACME Messaging, a default queue that is installed with qualifier @Default and a durable queue that has qualifier @Durable:

class MyMessageQueues {

   

   @Produces

   @ACMEQueue("defaultQueue")

   MessageSystemConfiguration defaultQueue = new MessageSystemConfiguration();

   

   @Produces @Durable @ConversationScoped

   @ACMEQueue("durableQueue")

   MessageSystemConfiguration producerDefaultQueue() {

      MessageSystemConfiguration config = new MessageSystemConfiguration();

      config.setDurable(true);

      return config;

   }

}

Looking first at the default queue, in addition to the @Produces annotation, the generic configuration annotation ACMEQueue, is used, which defines this to be a generic configuration point for ACME messaging (and cause a whole set of beans to be created, exposing for example the dispatcher). The generic configuration annotation specifies the queue name, and the value of the producer field defines the messaging system's configuration (in this case we use all the defaults). As no qualifier is placed on the definition, @Default qualifier is inherited by all beans in the set.

The durable queue is defined as a producer method (as we want to alter the configuration of the queue before having Seam Solder use it). Additionally, it specifies that the generic beans created (that allow for their scope to be overridden) should be placed in the conversation scope. Finally, it specifies that the generic beans created should inherit the qualifier @Durable.

We can now inject our generic beans as normal, using the qualifiers specified on the configuration point:

class MessageLogger {

  

   @Inject

   MessageDispatcher dispatcher;

  

   void logMessage(Payload payload) {

      /* Add metaddata to the message */

      Collection<Header> headers = new ArrayList<Header>();

      ... 

      Message message = new Message(headers, payload);

      dispatcher.send(message);

   }

  

}

class DurableMessageLogger {

  

   @Inject @Durable

   MessageDispatcher dispatcher;

   

   @Inject @Durable

   DispatcherPolicy policy;

   

         

   /* Tweak the dispatch policy to enable duplicate removal */

   @Inject

   void tweakPolicy(@Durable DispatcherPolicy policy) {

      policy.removeDuplicates();

   }

  

   void logMessage(Payload payload) {

      ...

   }

}

It is also possible to configure generic beans using beans by sub-classing the configuration type, or installing another bean of the configuration type through the SPI (e.g. using Seam XML). For example to configure a durable queue via sub-classing:

@Durable @ConversationScoped

@ACMEQueue("durableQueue")

class DurableQueueConfiguration extends MessageSystemConfiguration {

      

   public DurableQueueConfiguration()

   {

      this.durable = true;

   }

}

And the same thing via Seam XML:

<my:MessageSystemConfiguration>

   <my:Durable/>

   <s:ConversationScoped/>

   <my:ACMEQueue>durableQueue</my:ACMEQueue>

   <my:durable>true</my:durable>

</my:MessageSystemConfiguration>

Having seen how we use the generic beans, let's look at how to define them. We start by creating the generic configuration annotation:

@Retention(RUNTIME)

@GenericType(MessageSystemConfiguration.class)

@interface ACMEQueue {


   String name();

   

}

The generic configuration annotation a defines the generic configuration type (in this case MessageSystemConfiguration); the type produced by the generic configuration point must be of this type. Additionally it defines the member name, used to provide the queue name.

Next, we define the queue manager bean. The manager has one producer method, which creates the queue from the configuration:

@GenericConfiguration(ACMEQueue.class) @ApplyScope

class QueueManager {


   @Inject @Generic

   MessageSystemConfiguration systemConfig;

   

   @Inject

   ACMEQueue config;

   

   MessageQueueFactory factory;

   

   @PostConstruct

   void init() {

      factory = systemConfig.createMessageQueueFactory();

   }

   

   @Produces @ApplyScope

   public MessageQueue messageQueueProducer() {

      return factory.createMessageQueue(config.name());

   }

}

The bean is declared to be a generic bean for the @ACMEQueue generic configuration type annotation by placing the @GenericConfiguration annotation on the class. We can inject the generic configuration type using the @Generic qualifier, as well the annotation used to define the queue.

Placing the @ApplyScope annotation on the bean causes it to inherit the scope from the generic configuration point. As creating the queue factory is a heavy operation we don't want to do it more than necessary.

Having created the MessageQueueFactory, we can then expose the queue, obtaining its name from the generic configuration annotation. Additionally, we define the scope of the producer method to be inherited from the generic configuration point by placing the annotation @ApplyScope on the producer method. The producer method automatically inherits the qualifiers specified by the generic configuration point.

Finally we define the message manager, which exposes the message dispatcher, as well as allowing the client to inject an object which exposes the policy the dispatcher will use when enqueing messages. The client can then tweak the policy should they wish.

@Generic(ACMEQueue.class)

class MessageManager {


   @Inject @Generic

   MessageQueue queue;

   

   @Produces @ApplyScope

   MessageDispatcher messageDispatcherProducer() {

      return queue.createMessageDispatcher();

   }

   

   @Produces

   DispatcherPolicy getPolicy() {

      return queue.getDispatcherPolicy();

   }   

   

}

Simply include the JAR file and the Seam Solder JAR in your project. For Maven projects, that means adding the following dependencies to your pom.xml:

         <dependency>

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

            <artifactId>seam-config-xml</artifactId>

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

            <scope>runtime</scope>

         </dependency>



         <dependency>

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

            <artifactId>seam-solder</artifactId>

            <version>${weld.extensions.version}</version>

         </dependency>

      

To take advantage of Seam Config, you need metadata sources in the form of XML files. By default these are discovered from the classpath in the following locations:

The beans.xml file is the preferred way of configuring beans via XML; however some CDI implementations will not allow this, so seam-beans.xml is provided as an alternative.

Here is a simple example. The following class represents a report:

class Report {

    String filename;

    

    @Inject

    Datasource datasource;

    

    //getters and setters

}

And the following support classes:

interface Datasource {

    public Data getData();

}


@SalesQualifier

class SalesDatasource implements Datasource {

  public Data getData()

  {

    //return sales data

  }

}


class BillingDatasource implements Datasource {

  public Data getData()

  {

    //return billing data

  }

}

The Report bean is fairly simple. It has a filename that tells the report engine where to load the report definition from, and a datasource that provides the data used to fill the report. We are going to configure up multiple Report beans via 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"
       xmlns:s="urn:java:ee" 
       xmlns:r="urn:java:org.example.reports">

 	<r:Report>  
 		<s:modifies/>
 		<r:filename>sales.jrxml<r:filename>
 		<r:datasource>
 			<r:SalesQualifier/>
 		</r:datasource>
  	</r:Report>
  	
 	<r:Report filename="billing.jrxml">
 		<s:replaces/>
 		<r:datasource>
 			<s:Inject/>
 			<s:Exact>org.example.reports.BillingDatasource</s:Exact>
 		</r:datasource>
  	</r:Report>  	
</beans>
    
         

The princess rescue example is a sample web app that uses Seam Config. Run it with the following command:

mvn jetty:run

And then navigate to http://localhost:9090/princess-rescue. The XML configuration for the example is in src/main/resources/META-INF/seam-beans.xml.

The main namespace is urn:java:ee. This namespace contains built-in tags and types from core packages. The built-in tags are:

as well as classes from the following packages:

Other namespaces are specified using the following syntax:

        xmlns:my="urn:java:com.mydomain.package1:com.mydomain.package2"

This maps the namespace my to the packages com.mydomain.package1 and com.mydomain.package2. These packages are searched in order to resolve elements in this namespace.

For example, you have a class com.mydomain.package2.Report. To configure a Report bean you would use <my:Report>. Methods and fields on the bean are resolved from the same namespace as the bean itself. It is possible to distinguish between overloaded methods by specifying the parameter types, for more information see Configuring Methods.

By default configuring a bean via XML creates a new bean; however there may be cases where you want to modify an existing bean rather than adding a new one. The <s:replaces> and <s:modifies> tags allow you to do this.

The <s:replaces> tag prevents the existing bean from being installed, and registers a new one with the given configuration. The <s:modifies> tag does the same, except that it merges the annotations on the bean with the annotations defined in XML. Where the same annotation is specified on both the class and in XML the annotation in XML takes precidence. This has almost the same effect as modifiying an existing bean, except it is possible to install multiple beans that modify the same class.

<my:Report>

    <s:modifies>

    <my:NewQualifier/>

</my:Report>



<my:ReportDatasource>

    <s:replaces>

    <my:NewQualifier/>

</my:ReportDatasource>

The first entry above adds a new bean with an extra qualifier, in addition to the qualifiers already present, and prevents the existing Report bean from being installed.

The second prevents the existing bean from being installed, and registers a new bean with a single qualifier.

Annotations are resolved in the same way as normal classes. Conceptually, annotations are applied to the object their parent element resolves to. It is possible to set the value of annotation members using the xml attribute that corresponds to the member name. For example:

public @interface OtherQualifier {

   String value1();

   int value2();

   QualifierEnum value();

}

<test:QualifiedBean1>

        <test:OtherQualifier value1="AA" value2="1">A</my:OtherQualifier>

</my:QualifiedBean1>

    

<test:QualifiedBean2>

        <test:OtherQualifier value1="BB" value2="2" value="B" />

</my:QualifiedBean2>