+ 
-
-
+
- Clone forge.github.com on GitHub. +
- Add a new .textile file in one of the sub directories of the docs directory. +
- Push the empty Textile file to your GitHub repository. +
- Use the GitHub Textile editor to write your docs and preview changes. Of course you can use your own editor if you prefer so. +
- Clone http://github.com/forge/website on GitHub. -
- Add a new .textile file in one of the sub directories of the docs directory. -
- Push the empty Textile file to your GitHub repository. -
- Use the GitHub Textile editor to write your docs and preview changes. Of course you can use your own editor if you prefer so. +
- + Download + and Un-zip Forge (or a recent + snapshot build + ) into a folder on your hard-disk, this folder will be your FORGE_HOME + +
- + Add '$FORGE_HOME/bin' to your path + ( + windows + , + linux + , + mac osx + ) + +
- * Consider installing Git and Maven 3.0.4+ (both optional) +
- Open a command prompt and run 'forge' (if you are on Windows, you will need to run forge.bat unless using a Unix-style terminal)
- How is forge different from Spring Roo @@ -191,10 +221,64 @@
Contribute or Get Involved
Build Forge from source
Got an idea? Want to get your feet wet? Do some ForgeStorming
@@ -188,8 +218,8 @@Share your work (send a pull request)
git pull upstream master9. If you made multiple commits, or if there were any merge commits created when you pulled from upstream, use rebase to squash them into a single commit, where 5 is the number of commits to rebase:
git rebase -i HEAD~5Change ‘pick’ to ‘s’ for each commit you wish to squash upwards. (If you do not change a line, it will not be modified.)
-1 pick ade2b1a Implemented FORGE-XX 2 s c3ae0a2 almost done 3 s c863bfb did more work 4 s af793ae Started working on FORGE-XX 5 pick 368bbb9 Previous commit written by someone else+
Change ‘pick’ to ‘f’ for each commit you wish to fixup upwards. (If you do not change a line, it will not be modified.)
+1 pick ade2b1a Implemented FORGE-XX 2 f c3ae0a2 almost done 3 f c863bfb did more work 4 f af793ae Started working on FORGE-XX 5 pick 368bbb9 Previous commit written by someone else
Once you are done, your commits should look like this:
1 ade2b1a Implemented FORGE-XX 2 368bbb9 Previous commit written by someone else
You can view your commits by typing ‘git log’.
@@ -201,10 +231,64 @@Share your work (send a pull request)
+
-
-
+
Release Guide
Updating Plugin Tags
If you are a Plugin author who wishes to ensure compatibility with the latest Forge release versions – ensure that you update your Plugin to use the corresponding Forge API version. You should also create a git branch in your Plugin repository – the name of this branch should be exactly the same as the Forge API version you wish to support.
@@ -165,10 +195,64 @@Uploading Release Documentation
+
Improve our documentation
+We need your help! Good documentation is one of the most important things for a great Forge experience. It’s really easy to help, so if you feel we are missing something in the docs, please add it. Be sure to follow the contribution guide when contributing documentation.
+The documentation is written in Textile, which is a lightweight markup language.
+Follow these steps to conribute documentation:
+-
+
The Textile Wikipedia page gives a good introduction about the markup language.
+Some technical details
+The Forge website is built using Awestruct, and the sources are on github.com. However you don’t have to install anything to contribute documentation! If you are interested in Awestruct anyway, you’ll find a guide on the github page about how to setup and use Awestruct.
++ +
-
-
+
Arquillian Testing
Introduction
Arquillian makes it easy to run automated tests in a container. If you haven’t heard about Arquillian yet, you should have a look at one of the videos.
@@ -166,8 +196,10 @@Installation
forge install-plugin arquillianSetting up containers
Before you can start writing tests you first need to add Arquillian to your project and set up a container to test in.
-arquillian setup --container <TAB>Upon the tab key the plugin will list all containers that are currently supported. Start typing one of the container names and remember to hit the
arquillian setup --containerType <TAB>Upon the tab key the plugin will list all container types (Eg. MANAGED,REMOTE,EMBEDDED). Choose one of these options and then choose the container name
+arquillian setup --containerType MANAGED --containerName <TAB>Upon the tab key the plugin will list all supported containers. Start typing one of the container names and remember to hit the
The plugin will now prompt you which versions you want to use for Arquillian, JUnit and the container connector. Depending on which container you are installing Forge will prompt for information such as the installation directory of the container.
That’s it! Arquillian is fully set up now. Take a look at your pom file and notice the new dependencies for JUnit and Arquillian and a profile for the selected container.
Adding multiple containers
@@ -186,10 +218,64 @@Exporting deployments
+
-
-
+
UI Scaffolding
Introduction
Forge’s default UI scaffolding generates a pure Java EE application with a JavaServer Faces User Interface. This UI includes support for creating, updating, deleting, pagination and searching. It also supports one-to-many, many-to-many, many-to-one and one-to-one relationships. The scaffolding uses pure JSF tags, with no runtime dependencies on any non-Java EE libraries.
@@ -201,10 +231,64 @@Customizing the Scaffold
+
-
-
+
Writing documentation
- We need your help! Good documentation is one of the most important things for broad adoption of Forge. It's really easy to help, so if you feel we are missing something in the docs, please add it :-) +Get Started
- The documentation is written in Textile, which is a lightweight markup language. -- Follow these steps to conribute documentation:
-
-
-
-
Some technical details
- The Forge website is built using Awestruct, and the sources are on http://github.com/forge/website. However you don't have to install anything to contribute documentation! If you are interested in Awestruct anyway, you'll find a guide on the github page about how to setup and use Awestruct. + +What should I do next?
+ Now you are ready to + build an application. + + ++
-
-
+
Add Commands to your 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("..."), 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.
Named commands
Named commands must, to little surprise, be given a name with which they are invoked. This is done by placing the {{@Command(“…”)}} 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("perform")
public void exampleCommand( @Option 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{code}$ exampleplugin perform
>> the command "perform" was invoked with the value: nullNotice 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.
+
-
-
+
Add Options to your Commands
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.
--named options
@@ -165,10 +195,8 @@ --named options
public class ExamplePlugin implements Plugin {
@Command("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:
$ exampleplugin perform --one cat --two dog
>> option one equals: cat
>> option two equals: dog- bc(command). $ exampleplugin perform —one cat —two dog
- $ exampleplugin perform —two dog —one cat
- $ exampleplugin perform —two dog -o cat
$ exampleplugin perform --one cat --two dog
$ exampleplugin perform --two dog --one cat
$ exampleplugin perform --two dog -o catOrdered options
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 valueOrdered options
For example, the following command accepts several options, named ‘one’, and ‘two’:
public class ExamplePlugin implements Plugin {
@Command("perform")
public void exampleCommand(
@Option String one,
@Option 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:
-$ exampleplugin perform cat dog
>> option one equals: cat
>> option two equals: dog{code}$ exampleplugin perform cat dog
>> option one equals: cat
>> option two equals: dogCombining --named and ordered options
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{code}@Option String value,
@Option(name="num") int numberThe 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("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);
}
}The above command, when executed, would produce the following output:
-$ exampleplugin perform --one cat --two dog bird lizard
>> option one equals: cat
>> option two equals: dog
>> option three equals: bird
>> option four equals: lizard{code}$ exampleplugin perform --one cat --two dog bird lizard
>> option one equals: cat
>> option two equals: dog
>> option three equals: bird
>> option four equals: lizardHowever, 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:
-$ exampleplugin --two dog bird --one cat lizard
>> option one equals: cat
>> option two equals: dog
>> option three equals: bird
>> option four equals: lizard{code}$ exampleplugin --two dog bird --one cat lizard
>> option one equals: cat
>> option two equals: dog
>> option three equals: bird
>> option four equals: lizard+
-
-
+
Add your Plugin to the Central Plugin Index (CPI)
Forge incorporates the concept of a “plugin market” for conveniently searching and installing available plugins, but in order to take advantage of this, you must first register your plugin in the Central Plugin Index.
What is the Central Plugin Index?
@@ -175,10 +205,64 @@Adding your Plugin to the Central Plugin Index
+
Configure a plugin repository for Forge
+The default plugin repository
+Forge uses the Central Plugin Index (introduced in an earlier section) as the default plugin repository. However, you may not be in a position to publish your plugins to everyone – they could be in private repositories sealed off from the rest of the world. In such an event, you can use your own custom plugin repository. This could be an organization-wide plugin repository.
+How does Forge locate the default plugin repository?
+Forge locates the default plugin repository through the DEFAULT_PLUGIN_REPO environment variable. The default value is https://raw.github.com/forge/plugin-repository/master/repository.yaml which is none other than the location of the YAML file for the Central Plugin Index.
Modifying the location of the default plugin repository
+The location of the default plugin repository can be modified by setting a new value to the DEFAULT_PLUGIN_REPO environment variable:
set DEFAULT_PLUGIN_REPO "http://example.com/repository.yaml"
To make this change permanent, you can create or modify the Forge script file that is executed by Forge on startup. The script file is named config and is located in directory identified by the FORGE_CONFIG_DIR environment variable. On most installations, the config file would be present in the .forge directory under your user home directory. On Linux/Unix/Mac OS, this is ~/.forge. On Windows 7 and higher, this would be C:\Users\<username>\.forge\.
The contents of this file include the following lines:
+@/* Automatically generated config file */;
about;
set HISTORY true;
set PROMPT "[\c{green}$PROJECT_NAME\c] \c{blue}\W\c \c{green}\$\c ";
set PROMPT_NOPROJ "[\c{red}no project\c] \c{blue}\W\c \c{red}\$\c ";
set DEFAULT_PLUGIN_REPO "https://raw.github.com/forge/plugin-repository/master/repository.yaml";
set IGNOREEOF 1;To modify the default plugin repository permanently, modify the value of the environment variable (in line 6), like so:
+@/* Automatically generated config file */;
about;
set HISTORY true;
set PROMPT "[\c{green}$PROJECT_NAME\c] \c{blue}\W\c \c{green}\$\c ";
set PROMPT_NOPROJ "[\c{red}no project\c] \c{blue}\W\c \c{red}\$\c ";
set DEFAULT_PLUGIN_REPO "http://example.com/repository.yaml";
set IGNOREEOF 1;We recommend that the contents of this custom plugin repository file, be synchronized with the contents of the default Central Plugin Index from time to time. The best way to do this, would be to maintain a fork of the Central Plugin Index. This will ensure that you can install plugins from both the central plugin index as well as from the private repositories.
++ +
-
-
+
Enable Piping between Commands
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 */;Enable Piping between Commands
+
-
-
+
Enable modular functionality with Facets
Frequently when writing plugins, it is not beneficial (sometimes detrimental) to enable all functionality of a plugin at the same time. For instance, let’s say you have written a plugin that adds security to an existing web application. Your plugin handles setup of the security dependencies, creation of database tables, and also supports class-configuration of an authentication/authorization provider. It does not make sense for you to create the configuration classes before the dependencies have been installed, because you will likely create compilation errors in the project due to missing APIs. This might be a good time to use facets.
What is a Facet?
@@ -239,10 +269,64 @@User input in Facets
+
-
-
+
Give your Plugin a name
-Each plugin should be given a name. This is done by adding the @org.jboss.seam.forge.shell.plugins.Alias annotation to your plugin class.
Each plugin should be given a name. This is done by adding the @org.jboss.forge.shell.plugins.Alias annotation to your plugin class.
By default, if no @Alias annotation is found, the lower-case Class name will be used; for instance, our ExamplePlugin, above, would be executed by typing:
$ examplepluginNow we will add a name to our plugin.
@Alias("example")
public class ExamplePlugin implements Plugin {
// commands
}Our named @Alias("example") ExamplePlugin would be executed by typing:
$ example{code}$ example{code}
+
-
-
+
Implement the Plugin interface
-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
{
}The first thing you must do in order to create a forge plugin, is create a new class and implement the org.jboss.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.forge.shell.plugins.Plugin;
public class ExamplePlugin implements Plugin
{
}You might also use the “plugins new-plugin” command to do this a little more quickly:
[example] example $ plugins new-plugin --named ExamplePlugin ? In which package would you like to create [ExamplePlugin], or enter for default: [com.example]Wrote ~/example/src/main/java/com/example/ExamplePlugin.java Picked up type <JavaResource>: com.example.ExamplePlugin[example] ExamplePlugin.java $ ls -apackage com.example; import javax.inject.Inject; import org.jboss.forge.shell.ShellPrompt;import org.jboss.forge.shell.plugins.Plugin; import org.jboss.forge.shell.plugins.Alias; import org.jboss.forge.shell.plugins.PipeOut; import org.jboss.forge.shell.plugins.Option; import org.jboss.forge.shell.plugins.Command;public class ExamplePlugin implements Plugin {@Inject private ShellPrompt prompt;@Command("run") public void run(PipeOut out, @Option(name="value") final String arg){ out.println("Executed command with value: " + arg); } }[example] ExamplePlugin.java $
As you can see, in addition to creating the Plugin class, this action has already created a blank command for us to customize.
+
-
-
+
Important APIs
Dependency Facet
A lot of Forge plugins make it easy to install extra libraries or frameworks to your project. In a Maven project this almost always result in adding new dependencies to your POM by copy pasting from some website. Make installing a framework easier by letting Forge do the POM work for the user.
@@ -191,15 +221,68 @@XML parsing and generation
Many plugins will have to read/write XML files (e.g. to generate configuration files). Forge has a convenient XML API.
Node xml = XMLParser.parse(resource.getResourceInputStream()); Node config = xml.getOrCreate("someelement"); config.createChild("sub").createChild("property@name=test").text("hello");resource.setContents(XMLParser.toXMLString(xml));
This will result in the following XML:
-<someelement>
<sub>
<property name="test">hello</property>
</sub>
</someelement>Code templates
+<someelement>
<sub>
<property name="test">hello</property>
</sub>
</someelement>
+
-
-
+
Developing a Plugin
Part of Forge’s architecture is to allow extensions to be created with extreme ease. This is done using the same programming model that you would use for any CDI or Java EE application, and you should quickly recognize the annotation-driven patterns and practices applied.
A Forge plugin could be as simple as a tool to print files to the console, or as complex as deploying an application to a server, ’tweet’ing the status of your latest source-code commit, or even sending commands to a home-automation system; the sky is the limit\!
@@ -162,10 +192,64 @@Developing a Plugin
+
-
-
+
Make your Plugin available to Forge
All plugin installation should take place using the $ forge meta-command. For more information on this command, type:$ help forge
As a Git repository
+
-
-
+
Reference Forge API
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 built-in plugin project facet.
Using Forge
@@ -168,10 +198,64 @@Using Forge
+
-
-
+
Ensure all referenced libraries are on the CLASSPATH
-If you are experiencing overwhelming issues with a ClassLoader, and cannot work around the modular environment, Forge offers an alternate Plugin packaging mode that can be activated by setting a flag in your Plugin’s src/main/resources/META-INF/forge.xml file:
+Troubleshooting Forge ClassLoaders
+If you are experiencing ClassLoader issues, when loading or running your Plugin (but not during unit tests), the cause might be the ClassLoading structure of JBoss Forge versions 1.3.2.Final and earlier. This is typically the case if your the Maven project implementing your Plugin uses Maven dependencies. In these cases, you could configure Forge to use an alternate Plugin ClassLoading strategy, activated by setting a flag in your Plugin’s src/main/resources/META-INF/forge.xml file:
<forge>
<dependencies-as-resource-root/>
</forge>This will cause Forge to bundle all dependencies for your Plugin in the Plugin module itself, instead of creating a separate “dependencies” module, with a separate ClassLoader.
+Note! When you configure Forge to use the “dependencies-as-resource-root” option, your project must explicitly import any transitive Maven dependencies, as the Forge ClassLoader structure prevents transitive dependencies to be “seen” by your plugin. A good help to find all transitive dependencies is the “mvn dependency:tree” command, which should be run in your Plugin’s Maven project.
As a last resort, you may also shade code into your plugin’s JAR file; however, this is extremely discouraged, since you may cause ClassCastExceptions at runtime, and this increases the burden on Class scanning at boot time, because CDI will scan all classes in your Plugin JAR file.
-Using Forge to set up Shading
[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.1Notice that the pom.xml file has been modified and now includes a shade configuration including commons-collections.
@@ -174,14 +205,71 @@Ensure all referenced libraries are on the CLASSPATHThis should be repeated for each dependency as necessary. Notice that our POM has been updated with the configuration:
<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>
<relocations>
<relocation>
<pattern>org.apache.commons.collections</pattern>
<shadedPattern>com.example.forge.plugin.shaded.apache.collections</shadedPattern>
</relocation>
</relocations>
</configuration>
</execution>
</executions>
</plugin>
When you build your plugin, you should see confirmation output from the Maven Shade Plugin looking something like this:
- [INFO] --- maven-shade-plugin:1.4:shade (default) @ example-plugin ---
[INFO] Excluding org.jboss.seam.forge:forge-shell-api:jar:{version} from the shaded jar.
[INFO] Excluding org.jboss.seam.forge:forge-parser-java-api:jar:{version} from the shaded jar.
[INFO] Excluding org.jboss.seam.forge:forge-parser-xml:jar:{version} from the shaded jar.
[INFO] Excluding org.jboss.shrinkwrap.descriptors:shrinkwrap-descriptors-api:jar:{version} from the shaded jar.
[INFO] Excluding javax.enterprise:cdi-api:jar:{version} from the shaded jar.
[INFO] Excluding org.jboss.spec.javax.interceptor:jboss-interceptors-api:jar:{version} from the shaded jar.
[INFO] Excluding javax.annotation:jsr250-api:jar:{version} from the shaded jar.
[INFO] Excluding javax.inject:javax.inject:jar:{version} from the shaded jar.
[INFO] Including commons-collections:commons-collections:jar:3.2.1 in the shaded jar.
[INFO] Replacing original artifact with shaded artifact.
[INFO] Replacing ~/Desktop/example-plugin/target/example-plugin-1.0.0-SNAPSHOT.jar
with ~/Desktop/example-plugin/target/example-plugin-1.0.0-SNAPSHOT-shaded.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
+ [INFO] --- maven-shade-plugin:1.4:shade (default) @ example-plugin ---
[INFO] Excluding org.jboss.seam.forge:forge-shell-api:jar:{version} from the shaded jar.
[INFO] Excluding org.jboss.seam.forge:forge-parser-java-api:jar:{version} from the shaded jar.
[INFO] Excluding org.jboss.seam.forge:forge-parser-xml:jar:{version} from the shaded jar.
[INFO] Excluding org.jboss.shrinkwrap.descriptors:shrinkwrap-descriptors-api:jar:{version} from the shaded jar.
[INFO] Excluding javax.enterprise:cdi-api:jar:{version} from the shaded jar.
[INFO] Excluding org.jboss.spec.javax.interceptor:jboss-interceptors-api:jar:{version} from the shaded jar.
[INFO] Excluding javax.annotation:jsr250-api:jar:{version} from the shaded jar.
[INFO] Excluding javax.inject:javax.inject:jar:{version} from the shaded jar.
[INFO] Including commons-collections:commons-collections:jar:3.2.1 in the shaded jar.
[INFO] Replacing original artifact with shaded artifact.
[INFO] Replacing ~/Desktop/example-plugin/target/example-plugin-1.0.0-SNAPSHOT.jar
with ~/Desktop/example-plugin/target/example-plugin-1.0.0-SNAPSHOT-shaded.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
+ Default dependencies
+ During plugin installation, Forge adds certain modules as dependencies to the plugin module. Forge adds the org.jboss.forge.javaee.api, org.jboss.forge.maven.api, org.jboss.forge.scaffold.api, org.jboss.forge.shell.api, org.jboss.seam.render and javax.api modules as dependencies to your plugin. These modules already exist in a Forge installation and are added as dependencies to the plugin module, so they’re readily available during plugin execution.
+ If you chose to use the default plugin packaging mode, Forge creates an additional ‘dependencies’ module as a dependency for your plugin during installation. The ‘dependencies’ module contains all the dependencies with an effective scope of runtime, that are present anywhere in the dependency hierarchy of your plugin project. The artifacts constituting the dependencies are added as resource roots to the ‘dependencies’ module. In general, project POM dependencies with org.jboss.forge groupId will be omitted from the ‘dependencies’ module.
<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>
<relocations>
<relocation>
<pattern>org.apache.commons.collections</pattern>
<shadedPattern>com.example.forge.plugin.shaded.apache.collections</shadedPattern>
</relocation>
</relocations>
</configuration>
</execution>
</executions>
</plugin>[INFO] --- maven-shade-plugin:1.4:shade (default) @ example-plugin ---
[INFO] Excluding org.jboss.seam.forge:forge-shell-api:jar:{version} from the shaded jar.
[INFO] Excluding org.jboss.seam.forge:forge-parser-java-api:jar:{version} from the shaded jar.
[INFO] Excluding org.jboss.seam.forge:forge-parser-xml:jar:{version} from the shaded jar.
[INFO] Excluding org.jboss.shrinkwrap.descriptors:shrinkwrap-descriptors-api:jar:{version} from the shaded jar.
[INFO] Excluding javax.enterprise:cdi-api:jar:{version} from the shaded jar.
[INFO] Excluding org.jboss.spec.javax.interceptor:jboss-interceptors-api:jar:{version} from the shaded jar.
[INFO] Excluding javax.annotation:jsr250-api:jar:{version} from the shaded jar.
[INFO] Excluding javax.inject:javax.inject:jar:{version} from the shaded jar.
[INFO] Including commons-collections:commons-collections:jar:3.2.1 in the shaded jar.
[INFO] Replacing original artifact with shaded artifact.
[INFO] Replacing ~/Desktop/example-plugin/target/example-plugin-1.0.0-SNAPSHOT.jar
with ~/Desktop/example-plugin/target/example-plugin-1.0.0-SNAPSHOT-shaded.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] --- maven-shade-plugin:1.4:shade (default) @ example-plugin ---
[INFO] Excluding org.jboss.seam.forge:forge-shell-api:jar:{version} from the shaded jar.
[INFO] Excluding org.jboss.seam.forge:forge-parser-java-api:jar:{version} from the shaded jar.
[INFO] Excluding org.jboss.seam.forge:forge-parser-xml:jar:{version} from the shaded jar.
[INFO] Excluding org.jboss.shrinkwrap.descriptors:shrinkwrap-descriptors-api:jar:{version} from the shaded jar.
[INFO] Excluding javax.enterprise:cdi-api:jar:{version} from the shaded jar.
[INFO] Excluding org.jboss.spec.javax.interceptor:jboss-interceptors-api:jar:{version} from the shaded jar.
[INFO] Excluding javax.annotation:jsr250-api:jar:{version} from the shaded jar.
[INFO] Excluding javax.inject:javax.inject:jar:{version} from the shaded jar.
[INFO] Including commons-collections:commons-collections:jar:3.2.1 in the shaded jar.
[INFO] Replacing original artifact with shaded artifact.
[INFO] Replacing ~/Desktop/example-plugin/target/example-plugin-1.0.0-SNAPSHOT.jar
with ~/Desktop/example-plugin/target/example-plugin-1.0.0-SNAPSHOT-shaded.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------org.jboss.forge.javaee.api, org.jboss.forge.maven.api, org.jboss.forge.scaffold.api, org.jboss.forge.shell.api, org.jboss.seam.render and javax.api modules as dependencies to your plugin. These modules already exist in a Forge installation and are added as dependencies to the plugin module, so they’re readily available during plugin execution.org.jboss.forge groupId will be omitted from the ‘dependencies’ module.+
-
-
+
Test your Plugin
When developing plugins, it is recommended to use the provide Unit and Integration Test Harness (based on Arquillian.) Not only do your plugin’s Unit and Integration tests ensure that your plugin will function on your computer, but because tests are run when plugins are installed into a Forge runtime, they also ensure that your plugin will function on your users computers.
Install the Test Harness
@@ -162,7 +192,16 @@Install the Test Harness
<dependency>
<groupId>org.jboss.forge</groupId>
<artifactId>forge-test-harness</artifactId>
<version>${forge.api.version}</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.jboss.forge</groupId>
<artifactId>forge-shell</artifactId>
<version>${forge.api.version}</version>
<scope>test</scope>
</dependency>Extend AbstractShellTest or SingletonAbstractShellTest
AbstractShellTest boots the Shell for each individual test method, while SingletonAbsractShellTest boots the Shell only once per test class, where each method operates on the same instance.
-+package com.example.plugin;import javax.inject.Inject;import org.jboss.arquillian.api.Deployment; import org.jboss.forge.project.Project; import org.jboss.forge.project.dependencies.DependencyResolver; import org.jboss.forge.test.AbstractShellTest; import org.jboss.shrinkwrap.api.spec.JavaArchive; import org.junit.Assert; import org.junit.Test;public class ExamplePluginTest extends AbstractShellTest { // Notice that you may use injection to do verification of the internal state of the system. // Or to perform additional operations. @Inject private DependencyResolver resolver;@Deployment public static JavaArchive getDeployment() { // The deployment method is where you must add references to your classes, packages, and // configuration files, via Arquillian. return AbstractShellTest.getDeployment().addPackages(true, ExamplePlugin.class.getPackage()); }@Test public void testInstallPrettyfaces() throws Exception { // Create a new barebones Java project Project p = initializeJavaProject();// Queue input lines to be read as the Shell executes. queueInputLines("y");// Execute a command. If any input is required, it will be read from queued input. getShell().execute("echo hi there");Assert.assertNotNull(resolver); } }
+package com.example.plugin;import javax.inject.Inject;import org.jboss.arquillian.container.test.api.Deployment; import org.jboss.forge.project.Project; import org.jboss.forge.project.dependencies.DependencyResolver; import org.jboss.forge.test.AbstractShellTest; import org.jboss.shrinkwrap.api.spec.JavaArchive; import org.junit.Assert; import org.junit.Test;public class ExamplePluginTest extends AbstractShellTest { // Notice that you may use injection to do verification of the internal state of the system. // Or to perform additional operations. @Inject private DependencyResolver resolver;@Deployment public static JavaArchive getDeployment() { // The deployment method is where you must add references to your classes, packages, and // configuration files, via Arquillian. return AbstractShellTest.getDeployment().addPackages(true, ExamplePlugin.class.getPackage()); }@Test public void testInstallPrettyfaces() throws Exception { // Create a new barebones Java project Project p = initializeJavaProject();// Queue input lines to be read as the Shell executes. queueInputLines("y");// Execute a command. If any input is required, it will be read from queued input. getShell().execute("echo hi there");Assert.assertNotNull(resolver); } }
Invoking commands in your test
+In the above test, commands are invoked in the booted Shell through the invocation of getShell().execute(...) sequence. The Shell.execute(...) method accepts a shell command string with command options, as it’s parameter.
You may want to provide inputs during the execution of the command when you use the ShellPrompt API in your plugin. This is possible through the use of the queueInputLines(...) method. It accepts a variable number of String arguments. Each argument corresponds to an input line that is provided to the displayed prompt.
Note that queueInputLines(…) should be invoked prior to the execution of the Shell.execute(…) method. Arguments queued up before command invocation would then be provided as inputs when prompted. Queueing arguments after invoking Shell.execute(…) has no effect on the current command invocation context; the queued arguments will be used in the next command invocation.
+Add other dependencies
+Because of the modular structure of Forge, you may need to add additional test-scoped dependencies to your plugin. After all, not all commands are made available by adding the test harness artifact as a dependency.
+For instance, if you want to invoke commands provided by the built-in Java EE plugin (like the persistence, entity, or rest commands), you’ll need to add the org.jboss.forge:forge-javaee-impl artifact as a test-scoped dependency, like so:
<dependency>
<groupId>org.jboss.forge</groupId>
<artifactId>forge-javaee-impl</artifactId>
<scope>test</scope>
</dependency>Such dependencies are expected to be CDI bean archives that contain the desired Forge plugins you wish to utilize during test execution.
Run your Build
If done properly, you should now see your test execute during the Plugin build lifecycle.
$ buildWrite more tests
+
-
-
+
Affiliation
This reference guide was written for Forge: a tool from JBoss by Red Hat, Inc.
+
-
-
+
Writing Basic Java EE Application
For the most part, people interested in Forge are likely interested in creating web-applications. Thusly, this chapter will overview the basic steps to generate such an application using Forge.
Get Started with Scaffolding
@@ -165,12 +195,23 @@Start Forge
Create a new project
$ new-project --named {name} --topLevelPackage {com.example.project} --projectFolder {/directory/path}Set up scaffolding
-Press ENTER to confirm installation of any required facet dependencies and/or packaging types:
+Press ENTER to confirm installation of any required facet dependencies and/or packaging types. You should get these 3 questions:
+$ scaffold setup? No scaffold type was provided, use Forge default? [Y/n]
$ scaffold setup? No scaffold type was selected, use default [JavaServer Faces]? [Y/n]
? Scaffold provider [faces] is not installed. Install it? [Y/n]
? Facet [forge.maven.WebResourceFacet] requires packaging type(s) [war], but is currently [jar]. Update packaging? (Note: this could deactivate other plugins in your project.) [Y/n] Press ENTER for those 3 questions. Next, we have:
+Use which version of 'jboss-javaee-6.0' ?Again, press ENTER for the default value:
+? Choose an option by typing the number of the selection [*-default] Keep on pressing ENTER to choose default values for the next questions:
+? Create scaffold in which sub-directory of web-root? (e.g. http://localhost:8080/ForgeTest/DIR) [/]Set up persistence (JPA)
Press ENTER to confirm installation of any required facet dependencies and/or packaging types, and remember to press TAB if you are not sure what comes next.
$ persistence setup --provider {your JPA implementation} --container {your container}If you choose a Java EE container, press ENTER to answer default values for the next questions:
+? Do you want to install a JPA 2 metamodel generator? [y/N]If you choose HIBERNATE:
+? The JPA provider [HIBERNATE], also supplies extended APIs. Install these as well? [y/N]If you do not wish to use a Java EE container default data-source, you can also specify additional connection parameters such as JNDI data-source names, JDBC connection information, and data-source types. Note, however, that this means you will probably need configure your application server to provide this new data-source and/or database connection.
Create some JPA entities:
$ entity --named CustomerCreate some JPA entities:
Customer.java $ field string --named firstName
Customer.java $ field string --named lastNameWhile “holding” most files, you may inspect them using ‘ls’.
+Customer.java $ ls[fields] private::String::firstName; private::String::lastName; private::int::version; private::long::id;[methods] public::getFirstName()::String public::getId()::long public::getLastName()::String public::getVersion()::int public::setFirstName(final String firstName)::void public::setId(final long id)::void public::setLastName(final String lastName)::void public::setVersion(final int version)::void public::toString()::StringCustomer.java $
Picking up other files
+As stated above, creating a new entity will automatically “pick-up” and “hold” that file. When a file is “held”, that file is the context that operations are performed in. To change that context and “pickup” another file, use the pick-up command.
Eg. $ pick-up src/main/java/com/company/Client.java
Generate some UI scaffolding!
Once you have created fields in the entity, it’s time to generate some scaffolding. Since we have already installed our scaffold, this step is easy. While “holding” Customer.java, type:
-Customer.java $ scaffold from-entity? No scaffold type was selected, use default (JSF)? [Y/n] Wrote /src/main/java/com/scaffold/domain/Customer.java Wrote /src/main/java/com/scaffold/view/CustomerBean.java Wrote /src/main/webapp/scaffold/customer/view.xhtml Wrote /src/main/webapp/scaffold/customer/create.xhtml Wrote /src/main/webapp/scaffold/customer/list.xhtml ***SUCCESS*** Generated UI for [com.scaffold.domain.Customer]Customer.java $
That’s it! Now build your project and deploy it onto your JBoss Application Server instance:
+That’s it! Now build your project and deploy it onto your Java EE Application Server of choice:
$ buildOr, if you want to control the build more finely, you can also build your new project using Maven. (If you do not have maven installed, Forge will use its provided embedded Maven support.)
+Or, to control the build more finely, you can also build your new project using native Maven commands. (If you do not have maven installed, Forge will use its provided embedded Maven support.)
$ mvn clean packageDeploy/undeploy to AS7
+(Optional) Deploy/undeploy to AS7
First you need to install the AS7 Forge Plugin by typing the following command:
$ forge install-plugin jboss-as-7Next, set up the plugin in your project:
@@ -198,10 +242,64 @@That’s it! Access your deployed application at:
+
-
-
+
Configure HTTP Proxy
If you are behind a firewall and require the use of an HTTP Proxy, you must configure several settings in Forge and Maven:
1. Open the user configuration in ~/.forge/config.xml (located in your home directory.)
2. Add the ‘proxy’ tag and required information:
-<proxy>
<host>proxy-host-name</host>
<port>proxy-port</port>
<!-- The entries below are necessary only if your proxy needs authentication -->
<username>proxy-user-name</username>
<password>proxy-password</password>
</proxy><?xml version="1.0" encoding="UTF-8" standalone="no"?>
<configuration>
<proxy>
<host>proxy-host-name</host>
<port>proxy-port</port>
<!-- The entries below are necessary only if your proxy needs authentication -->
<username>proxy-user-name</username>
<password>proxy-password</password>
</proxy>
</configuration>3. Set up the proxy information in your Maven settings.xml. For detailed instructions, follow the Maven proxy guide here.
<settings>
<proxies>
<proxy>
<active>true</active>
<protocol>http</protocol>
<host>proxy.somewhere.com</host>
<port>8080</port>
<username>proxyuser</username>
<password>somepassword</password>
<nonProxyHosts>www.google.com|*.somewhere.com</nonProxyHosts>
</proxy>
</proxies>
</settings>4. Restart Forge
@@ -167,10 +197,64 @@Configure HTTP Proxy
+
Debugging Forge
+Forge logfiles
+As of CR1 (and SNAPSHOTS since Beta5,) Forge produces a debug logfile located at:
+$HOME/.forge/runtime.logEclipse integrated debugging
+A new feature of JBoss Tools 4.0 is the debug option of the Forge plugin.
+Under Window > Preferences > Forge the option “Start Forge in Debug Mode” enables you to fully debug the Forge runtime. Hitting the famous [CTRL+4] keys will then launch Forge in Eclipse debugger. This way you may watch Forge registering and launching your plugin. Don’t forget to switch to Debug perspective.
+Depending of your use case you may additionally change the Forge runtime by registering your current Forge core source tree under “Installed Forge Runtimes”.
+Current Shortcomings
+The current eclipse plugin does not yet associate sources automatically, so you have to add relevant sources using “Edit Source Lookup” on the debug configuration. The generated debug configuration is available during the Forge debug session and will be cleaned up afterwards.
+Enable debug mode
+Start Forge by using the following parameter:
+forge --debugIf you don’t want to use the —debug parameter, you need to set the following FORGE_OPTS (JVM arguments) in your console before starting Forge (this does not work when running Forge in the IDE – it must be run from the command line).
+For Unix:
+export FORGE_OPTS="-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000"For Windows (note no quotes):
+set FORGE_OPTS=-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000Then run Forge. If you’ve done this step correctly, Java should state that it is waiting for the debugger to attach on port 8000.
+Connect the debugger
+If you are using Eclipse, in addition to having the Forge sources imported as projects in your workspace, you will need to create a new project (for this example, call it ‘maven-debug’), then right-click on that project, and click “Debug as → Remote Java Application”
+Make sure the remote debugger port is set to 8000 (or the port you’ve selected,) much like debugging Maven.
+Attach the sources
+If Eclipse complains that it cannot find the source attachment for a breakpoint, make sure to add all related Forge projects as source attachments to your new ‘maven-debug’ project by clicking the “Attach Sources” button.
++ +
-
-
+
FAQ
How can I contribute to forge?
+