Seam 3 Examples

Seam provides examples to raise awareness of functionality and to help developers understand how to put that functionality to use. They also serve as a QA tool for catching integration errors and, for designated examples, performance problems.

Examples lead: Shane Bryzak

Example types

Examples come in two different forms - simple examples that demonstrate a single feature of Seam, and composite examples that demonstrate how multiple features can be used together in a single application. For simple examples, the example source code should be placed within the module that the example is demonstrating. For the more complex composite examples, the source code should be placed in the top level examples branch in GIT.

We welcome your example contributions. After all, you are the developers who are out in the field and you know best what types of applications are being developed. If you aren't sure what to create, consider picking one of the examples from our list of example ideas.

Development guidelines

• Where possible, show off your features in a composite application. This has been one of Seam's key selling points, that we actually show off real world applications built in Seam. Simple, hello-world style, examples are largely useless they have a very tight focus (such as being the very first example, or showing off a particular feature).
• Involve others in the team early on. Often they can help you out and advise you on how to design your example so that functional tests can be added
• Provide tests for all examples - not only does this show users how to test their app, it also means we get real world tests
• Make sure you provide both command line and JBoss Tools options for building and running/deploying the example. In general, you should use Maven to build the project on the command line, and check that the import into JBoss Tools works well. It is important that provide step-by-step instructions for importing the example into JBDS. These instructions should be tested as part of your release process
• Make sure the examples support for Copy & Paste programming - the user should be able to copy the example that is close to their needs and extend it with their customizations
• Wherever possible, use the examples as the basis for tutorials (e.g. in the Getting Started Guide). This both decreases the overhead required in creating tutorials, and offers great value to users. Producing an example with no tutorial, and no comments is a pointless exercise. The tutorial should provide every step necessary to get the example up and running, assuming the user is a novice. Involve others on the project team here, as they can check your tutorial steps all work.
• Each example should provide a readme.txt or readme.html that explains the following:
  • Purpose of the example (for example, to demonstrate feature X by illustrate how that API can be used to perform A, B and C.)
  • Prerequisites (e.g. The AS has been installed and the appropriate properties files have been updated); Step by Step setup for the example
  • Step by Step execution of the example (e.g. ant deploy or mvn clean install or run -c server1; run -c server2 or using your browser hit: http://localhost:8080/MyNewApp
  • Expected results (you should see Hello World on the console or you can now navigate the web-based application)
  • the readme.txt should include the maintainer of the example (along with contact info). This may simply point to the examples' POM.
• Make sure you update and review your examples regularly. You should check your example works for each release. You should review your examples at a regular interval to ensure they paint a coherent story. For example, they promote the current preferred way of using your framework, and that there is a good distribution of examples across the features offered by the framework.