(THIS IS A WORK IN PROGRESS STARTED SEPTEMBER 14, 2010)
Overview
JBoss Tools and JBDS provide access to numerous zipped project examples via the Help->Project Examples menu. Each project example appears in a category that organizes them into broad groups for ESB, Seam, BPEL, and so on. When the user selects one of the examples and clicks Finish, the example is imported into their workspace and (if the "Show the Quick Fix dialog" box is checked) work through some of the available quick fixes to help the example work in their environment.
There are three criteria for each project example...
- The zip for the project example is essentially the exported archive file for an Eclipse project.
- A project examples XML file registered for JBoss Tools or JBDS using the org.jboss.tools.project.examples.projectExamplesXml extension point.
- An entry in the XML file describing the project and any special requirements.
Project Example Zip File
The project example zip file is created by right-clicking on a project in the Package Explorer or Project Explorer and selecting Export on the popup menu. In the Export dialog, select General -> Archive File and click Next. Provide a path and file name for the archive file, specify which files should be in the archive, and click Finish.
These project example zip files may be contained in the SVN repository in a workspace directory such as "http://anonsvn.jboss.org/repos/jbosstools/workspace/myworkspace/myexamplefile.zip" or it may be found in the http://download.jboss.org/jbosstools/examples directory on the server.
NOTE: WE NEED TO SPECIFY WHERE THE EXAMPLE ZIP SHOULD BE LOCATED - JBT vs. JBDS.
Registered Project Examples XML File
There are a few project examples xml files that exist today. When adding a new example, it should be added to the lowest possible project example xml version it can work with. If it's a new example that doesn't work in an existing version, a new example xml is created and that is added as an additional example file.
For instance, if you are adding a new ESB example that will run on JBoss Tools version 3.1 (i.e. ESB 4.7 is supported), go ahead and add it to http://anonsvn.jboss.org/repos/jbosstools/workspace/examples/project-examples-3.1.xml.
However, if you're adding a new example for Teiid Designer, which didn't exist before JBoss Tools version 3.2, you would create a new project-examples-3.2.xml file if it didn't already exist. So the file would become http://anonsvn.jboss.org/repos/jbosstools/workspace/examples/project-examples-3.2.xml. Or if we end up with a version 3.3 and add new functionality there, we'd create http://anonsvn.jboss.org/repos/jbosstools/workspace/examples/project-examples-3.3.xml. And so on and so forth... This is an additive process.
Knowing what the target tooling platform will be is important, as what a project will "work with" is different between JBDS and JBoss Tools. For example, JBDS examples cannot use Maven since we don't have Maven plug-ins installed, but Maven can be used for JBoss Tools examples because Maven works in that environment.
Examples for JBDS should try and use jars from the actual supported runtimes instead of bundling them - JBoss Tools can be more liberal here.
If you add a new project example file, it needs to be registered so it can be found when the user uses the Project Examples wizard.
How Do I Publish A New XML File?
Once your file is ready to be published on download.jboss.org (rather than anonsvn.jboss.org), contact nboldt@redhat.com or open a JIRA assigned to Nick Boldt. You can also ping him on IRC (freenode channel #jbosstools or Red Hat channel #devstudio). Publishing the file is done via this script: http://anonsvn.jboss.org/repos/jbosstools/trunk/download.jboss.org/jbosstools/examples/publishExample.sh
Registering a new Project Examples XML File
We currently register example xml files in the org.jboss.tools.community.project.examples plug-in in SVN. You can find it at http://anonsvn.jboss.org/repos/jbosstools/trunk/examples/plugins/org.jboss.tools.community.project.examples.
Currently there are two file URLs registered in org.jboss.tools.community.project.examples...
To add another file, simply add a new instance of the "org.jboss.tools.project.examples.projectExamplesXml" extension point.
<extension
point="org.jboss.tools.project.examples.projectExamplesXml"
name="My New Example File">
<url>MY-EXAMPLE-XML-FILE-URL</url>
<experimental>false</experimental>
</extension>
New Entry in Project Examples XML File
Once you know which file to add your new example to, you can create a new entry for your example. Each of these files follows the same pattern - the root is <projects> and each new entry is a <project>. For example:
<projects>
<project>
<category>My Category Display Name</category>
<name>My Project Example Name</name>
<included-projects>NAME-OF-THE-PROJECT-EXPORTED-IN-THE-ZIP-FILE</included-projects>
<shortDescription>Brief Description</shortDescription>
<description>Long Description</description>
<size>22645</size> <!-- size of the zip file -->
<url>MY-ZIP-FILE-URL</url>
</project>
</projects>
Let's break this down a little.
- The <category> tags are used to provide the high-level grouping in the tree of the Project Examples wizard. For instance, if you have "My Category" as the category and "My Example" as the <name> of the project, you should see "My Category -> My Example" appear in the tree.
- The <name> tags are used to provide the display name for the Project Example. This does not need to be the same as what is included in the file itself as the actual project name.
- The <included-projects> tags contain the actual names of the projects in the zip file. It is important to get the name exactly right or the Project Examples wizard will not be able to successfully import the project.
- NOTE: I don't know where the <shortDescription> is actually used in the wizard.
- The <description> tags contain the description text displayed on the Project Examples wizard page when the project is selected.
- The <size> tags are used to display the file size of the example zip to give the user an idea of how big a file it is.
- The <url> tags contain the actual URL to the project example zip. The project example engine uses Eclipse ECF Framework so the URLs can be ftp, http, https (with and without authentication), a local file, etc.
NOTE: WE ALSO NEED TO DOCUMENT HOW TO USE THE <fixes> TAGS:
<fixes>
<fix type="wtpruntime">
<property name="allowed-types">org.jboss.ide.eclipse.as.runtime.eap.43, org.jboss.ide.eclipse.as.runtime.42</property>
<property name="eclipse-projects">registration,registration-ejb,registration-ear</property>
<property name="description">This project example requires the JBoss EAP 4.3 or JBoss AS 4.2.x</property>
</fix>
<fix type="seam">
<property name="allowed-versions">2.0.0, 2.0.1, 2.0.2</property>
<property name="eclipse-projects">registration</property>
<property name="description">This project example requires Seam version 2.0</property>
</fix>
<fix type="plugin">
<property name="id">org.testng.eclipse</property>
<property name="versions">5.8.0, 5.9.0</property>
<property name="description">The TestNG plugin is required if you want to run Seam tests. You can install it using the following update site: http://beust.com/eclipse</property>
</fix>
</fixes>
General Tips
Here are some general tips for how to setup the examples:
- Don't require users to download multiple examples, if one can suffice (i.e. initially one example = one project, that is not the case anymore. one example can contain multiple examples. Many of the ESB examples suffers from this)
- Do not refer to specific named JDK's, use Execution environments (this removes the need for any quickfixing when it comes to jdk and java runtime matching)
- Server runtimes do not have execution environments so use the names our installer/runtimesetup will most likely give them so it will be found automatically.
- Make sure to use the quickfix options to express what range of servers/runtimes it will work with.
Still to Work In:
> My second set of questions goes back to JBIDE-5645 and the issue I was seeing where the versions of the files in http://download.jboss.org/jbosstools/examples doesn't match what's in SVN.
>
> If we're pointing the community examples file at http://anonsvn.jboss.org/repos/jbosstools/workspace/examples/project-examples-3.1.xml instead of http://download.jboss.org/jbosstools/example/project-examples-3.1.xml, that explains the differences.
We should not be pointing to any examples in svn since svn locations are not stable. If we are that is a bug.
> As we add more and more examples, we really need to standardize a process for getting new ones into the mix and how we migrate the older ones forward.
>
> Do we have a strategy in place? If not, we seriously need to develop one quickly. Each time we release and add more examples, this mess will get bigger.
No strategy beyond above and yes we should get it written down since so many seem to think svn is a great place to store this even though it will constantly break.
Optimally we would push these to the maven repo instead and get them from there but right now download.jboss.org is where it is at.