<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<body link="#355491" alink="#4262a1" vlink="#355491" style="background: #e2e2e2; margin: 0; padding: 20px;">
<div>
<table cellpadding="0" bgcolor="#FFFFFF" border="0" cellspacing="0" style="border: 1px solid #dadada; margin-bottom: 30px; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td>
<table border="0" cellpadding="0" cellspacing="0" bgcolor="#FFFFFF" style="border: solid 2px #ccc; background: #dadada; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td bgcolor="#000000" valign="middle" height="58px" style="border-bottom: 1px solid #ccc; padding: 20px; -moz-border-radius-topleft: 3px; -moz-border-radius-topright: 3px; -webkit-border-top-right-radius: 5px; -webkit-border-top-left-radius: 5px;">
<h1 style="color: #333333; font: bold 22px Arial, Helvetica, sans-serif; margin: 0; display: block !important;">
<!-- To have a header image/logo replace the name below with your img tag -->
<!-- Email clients will render the images when the message is read so any image -->
<!-- must be made available on a public server, so that all recipients can load the image. -->
<a href="http://community.jboss.org/index.jspa" style="text-decoration: none; color: #E1E1E1">JBoss Community</a></h1>
</td>
</tr>
<tr>
<td bgcolor="#FFFFFF" style="font: normal 12px Arial, Helvetica, sans-serif; color:#333333; padding: 20px; -moz-border-radius-bottomleft: 4px; -moz-border-radius-bottomright: 4px; -webkit-border-bottom-right-radius: 5px; -webkit-border-bottom-left-radius: 5px;"><h3 style="margin: 10px 0 5px; font-size: 17px; font-weight: normal;">
Creating Project Examples
</h3>
<span style="margin-bottom: 10px;">
modified by <a href="http://community.jboss.org/people/maxandersen">Max Rydahl Andersen</a> in <i>JBoss Tools</i> - <a href="http://community.jboss.org/docs/DOC-16578">View the full document</a>
</span>
<hr style="margin: 20px 0; border: none; background-color: #dadada; height: 1px;">
<div class="jive-rendered-content"><p>Project examples are created using a project examples xml file added to a project examples site. <br/>Defining project examples sites is described on <a class="jive-link-wiki-small" href="http://community.jboss.org/docs/DOC-14955">Project Examples Sites</a>.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>A project examples xml file is described in the attached project-examples_1_0.xsd schema. </p><p>The following is a definition of a project example within some site: </p><pre><br/><p><?xml version="1.0" encoding="UTF-8"?></p><p><projects xmlns="urn:jboss:project-examples:1.0"</p><p><span>    xmlns:xsi="</span><a class="jive-link-external-small" href="http://www.w3.org/2001/XMLSchema-instance" target="_blank">http://www.w3.org/2001/XMLSchema-instance</a><span>"</span></p><p>    xsi:schemaLocation="urn:jboss:project-examples:1.0</p><p><span>    </span><a class="jive-link-external-small" href="http://download.jboss.org/jbosstools/examples/project-examples_1_0.xsd" target="_blank">http://download.jboss.org/jbosstools/examples/project-examples_1_0.xsd</a><span>"></span></p><p>  <project></p><p>  ...</p><p>  </project></p><p></projects></p><br/></pre><h4>Simple Project Example</h4><p>A definition of a simple project example: </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre><p><project></p><p>    <category>Seam</category></p><p>    <name>registration</name></p><p>    <included-projects>registration, registration-ejb ...</included-projects></p><p>    <shortDescription>Seam Registration Example</shortDescription></p><p>    <description>This is a trivial example for the Seam tutorial. ...</description></p><p>    <size>31657984</size></p><p><span>    <url></span><a class="jive-link-external-small" href="http://...registration.zip" target="_blank">http://...registration.zip</a><span></url></span></p><p></project></p><br/></pre><p>Below is a description of the basic elements: </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><ul><li><strong>category</strong> - the category to which the project example belongs</li><li><strong>name</strong> - the project example name - it is used internally and isn't shown to the user</li><li><strong>included-projects</strong> - the projects included in the project example.  The Project Example engine will import only those projects included within this element.</li><li><strong>shortDescription</strong> - the short description (it is recommended to be a few words)</li><li><strong>description</strong> - the complete description of the project example (a few lines recommended)</li><li><strong>size</strong> - the archive size in bytes. This is an informative and optional element</li><li><strong>url</strong> - the URL which the zip archive is placed on; can be local or remote; optional</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>These are the minimal elements necessary to create a project example. <br/>In this example, the url has to point to the zip archive containing one or more Eclipse projects. </p><p>The category, name, shortDescription, description, size and url are shown in the project example wizard. </p><p><a href="http://community.jboss.org/servlet/JiveServlet/showImage/14212/ProjectExamples7.png"><span> http://community.jboss.org/servlet/JiveServlet/downloadImage/14212/ProjectExamples7.png </span></a></p><h4>Fixes/Requirements</h4><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The developer can define requirements that need to be satisfied in order the project example to work correctly. The Project Example engine will warn the user if the requirements aren't satisfied (see the figure) and fix some possible issues when the project example is imported.</p><p><a href="http://community.jboss.org/servlet/JiveServlet/showImage/102-14955-9-2270/ProjectExamples3.png"><span> http://community.jboss.org/servlet/JiveServlet/downloadImage/102-14955-9-2270/451-598/ProjectExamples3.png </span></a></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><a href="http://community.jboss.org/servlet/JiveServlet/showImage/102-14955-9-2274/projectExamples4.png"><span> http://community.jboss.org/servlet/JiveServlet/downloadImage/102-14955-9-2274/449-296/projectExamples4.png </span></a></p><p> The following is an example of how to define fixes/requirements: </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><fixes></p><p>  <fix type="wtpruntime"></p><p>    <property name="allowed-types">org.jboss.ide.eclipse.as.runtime.eap.43, org.jboss.ide.eclipse.as.runtime.42</property></p><p>    <property name="eclipse-projects">registration,registration-ejb,registration-ear</property></p><p>    <property name="required-components">esb</property></p><p>    <property name="description">This project example requires the JBoss EAP 4.3 or JBoss AS 4.2.x</property></p><p>  </fix>        </p><p>  <fix type="seam"></p><p>     <property name="allowed-versions">2.0.0, 2.0.1, 2.0.2</property></p><p>     <property name="eclipse-projects">registration</property></p><p>     <property name="description">This project example requires Seam version 2.0</property></p><p>  </fix>        </p><p>  <fix type="plugin" hard="true"></p><p>     <property name="id">org.testng.eclipse</property></p><p>     <property name="versions">[5.8.0</property></p><p><span>     <property name="description">The TestNG plugin is required if you want to run Seam tests. You can install it using the following update site: </span><a class="jive-link-external-small" href="http://beust.com/eclipse" target="_blank">http://beust.com/eclipse</a><span></property></span></p><p>  </fix></p><p></fixes></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Currently, the project examples engine recognizes 3 types of requirements: </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><ul><li> <strong>wtpruntime</strong> - if there is a requirement of the type wtpruntime, a project example will require WTP runtime described with properties.<p><strong>wtpruntime properties</strong></p><ul><li><strong>allowed-types</strong> - a list of WTP runtime types required by the project example, comma separated. If the workspace contains a runtime from the list, the requirement is satisfied.</li><li><strong>eclipse-projects</strong> - a list of Eclipse projects to which the requirement is related.  If the workspace contains a runtime of the corresponding type, the project example will  automatically add that runtime to the projects. <br/>For instance, if the developer creates a project example using a WTP/Seam runtime named <strong>Runtime A</strong> and the workspace contains  a compatible runtime named <strong>Runtime B</strong>, the Project Examples engine will fix the runtime name in <strong>Runtime B</strong> for all the projects listed in the eclipse-projects property. </li><li><strong>required-components</strong> - a list of comma separated components  that have to be contained in a WTP runtime. Possible values are <strong>esb</strong>, <strong>portlet</strong> and <strong>bpel</strong>. </li><li><strong>description</strong> - the text showing up in the UI if the requirement isn't satisfied</li></ul></li><li><strong>seam</strong> - a project example requires a Seam runtime</li><p><strong>Seam properties</strong></p><ul><li><strong>allowed-versions</strong> required Seam versions</li><li><strong>eclipse-projects</strong> - a list of Eclipse projects to which the requirement is related  <br/>The Seam runtime name will be fixed in the way similar to how it is done for the wtpruntime type. </li><li><strong>description</strong> - the text showing up in the UI if the requirement isn't satisfied</li></ul><li><strong>plugin</strong> - a project example requires a plugin</li><p><strong>Plugin properties</strong></p><ul><li><strong>id</strong> - plugin ID</li><li><strong>versions</strong> - required versions (the syntax is the same as in the Eclipse manifest file (<strong>isn't implemented yet</strong>) </li><li><strong>description</strong> - the text showing up in the UI if the requirement isn't satisfied</li></ul></ul><p>If the <strong>fix</strong> contains the <strong>hard</strong> argument, the project example won't be shown if the requirement isn't satisfied (<strong>isn't implemented yet</strong>) </p><h4>Cheatsheet/html welcome page</h4><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The developer can define an Eclipse cheatsheet or a html page that will be opened after importing a project example. </p><p>The following is an example: </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre><project><br/> ...<br/> <welcome type="cheatsheets" url="/booking/cheatsheets/booking.xml"/><br/> ...
</project></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The type of the <strong>welcome</strong> page can be <strong>cheatsheets</strong> or <strong>html</strong>.</p><p>The <strong>url</strong> is the address of an Eclipse cheatsheet or html page that needs to be opened. It can be a standard url address or a location within the workspace. </p><p><span>Eclipse cheatsheet examples can be found on  </span><a class="jive-link-external-small" href="http://anonsvn.jboss.org/repos/jbosstools/workspace/snjeza/seam-examples/booking22.zip" target="_blank">http://anonsvn.jboss.org/repos/jbosstools/workspace/snjeza/seam-examples/booking22.zip</a><span>. </span></p><p>The org.jboss.tools.project.examples.cheatsheet plugin includes several actions that can be used in a cheatsheet.</p><p>The Javadoc API contains the description of those actions.</p><h4>Maven Project examples</h4><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Such project examples require the m2eclipse-core, m2eclipse-wtp and JBoss Maven Project Examples feature. </p><p>There are three types of Maven project examples: </p><h5>Pure maven project examples</h5><p>Pure maven project examples are defined in the following way: </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre> <project> <br/>  ...
<importType>maven</importType><br/> <importTypeDescription>...</importTypeDescription><br/> ...<br/> </project> <br/></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The developer defines the <strong>maven</strong> importType element and creates a zip archive containing a pure maven project that doesn't have to include Eclipse settings. The project example engine will import the project and configure Eclipse settings. </p><p> If the user's environment doesn't satisfy the requirements (doesn't include m2eclipse, for instance), a text from the <strong>importTypeDescription</strong> element will be shown.<strong> </strong></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>See <a class="jive-link-external-small" href="https://issues.jboss.org/browse/JBIDE-6214">JBIDE-6214</a> for more details. </p><h5>Maven project examples based on a Maven archetype</h5><p>The following is an example: </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre><p><importType>archetype</importType></p><p><importTypeDescription>The project example requires ...</importTypeDescription></p><p><archetype></p><p>    <archetypeGroupId>org.jboss.weld.archetypes</archetypeGroupId></p><p>    <archetypeArtifactId>jboss-javaee6-webapp</archetypeArtifactId></p><p>    <archetypeVersion>1.0.1.Beta2</archetypeVersion></p><p><span>    <!-- <archetypeRepository></span><a class="jive-link-external-small" href="http://repository.jboss.org/nexus/content/groups/public/" target="_blank">http://repository.jboss.org/nexus/content/groups/public/</a><span></archetypeRepository>  --> </span></p><p>    <groupId>org.jboss.tools.examples</groupId></p><p>    <artifactId>jboss-javaee6-webapp</artifactId></p><p>    <version>0.0.1-SNAPSHOT</version></p><p>    <javaPackage>org.jboss.tools.examples</javaPackage>            </p><p>    <properties></p><p>        <property name="name" value="Java EE 6 webapp project"/></p><p>    </properties>        </p><p></archetype></p></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The developer defines the <strong>archetype</strong> importType element.</p><p>A Maven archetype is defined within the <strong>archetype</strong> element.</p><p>The project examples engine will create an archetype and configure an Eclipse project.</p><p>For more details see <a class="jive-link-external-small" href="https://issues.jboss.org/browse/JBIDE-7890">JBIDE-7890</a></p><p>This type of Maven project examples doesn't require creating any archive.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h5>Project examples based on a Maven/Eclipse project placed in a Git/SVN Repository</h5><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>For example: </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><project></p><p>   ...</p><p>   <url>git://github.com/seam/examples.git</url></p><p>   ...</p><p>   <importType>maven</importType></p><p>   <importTypeDescription>...</importTypeDescription></p><p>   <git></p><p>      <branches>master</branches></p><p>      <initialBranch>master</initialBranch></p><p>      <remoteName>origin</remoteName></p><p>      <directoryPath>examples</directoryPath></p><p>      <homeDirectory>/</homeDirectory></p><p>    </git></p><p>    ...</p><p></project></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><project></p><p>   ...</p><p><span>   <url></span><a class="jive-link-external-small" href="http://anonsvn.jboss.org/repos/richfaces/branches/community/3.3.X/examples/photoalbum/" target="_blank">http://anonsvn.jboss.org/repos/richfaces/branches/community/3.3.X/examples/photoalbum/</a><span></url></span></p><p>   ...</p><p>   <importType>maven</importType></p><p>   <importTypeDescription>...</importTypeDescription></p><p>   <svn/></p><p>   ...</p><p></project></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>A Git/SVN repository is defined using the <strong>url </strong>and <strong>git </strong>or <strong>svn </strong>element. </p><p><br/>The <strong>importType</strong> describes the type of a project in the repository and can be <strong>maven</strong> (a pure maven project)  or <strong>eclipse</strong> (an Eclipse project). If it is omitted, <strong>eclipse</strong> is assumed. </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The <strong>git</strong> element can consists of some additional elements (all optional)</p><ul><li>branches - a list of branches (comma separated) to be fetched  (optional, the default branch is master)</li><li>initialBranch - determines which local branch will be created and initially checked out  (optional, master by default)</li><li>remoteName - defines a name for the remote repository (optional, the default is "origin")</li><li>directoryPath - a path to which you want to clone the Git directory  (optional, the default is the last segment of the url without .git suffix)</li><li>homeDirectory - a directory within the git repository where the example is placed  (optional, the default is /)</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The <strong>svn</strong> element doesn't require any additional element because it is completelly defined by the <strong>url</strong>.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>See <a class="jive-link-external-small" href="https://issues.jboss.org/browse/JBIDE-8452">JBIDE-8452</a> for more details. </p><p>This type of project examples doesn't require creating any archive.</p><p>The project examples based on Maven/Eclipse projects placed on a SVN Repository require subclipse feature. </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><strong>Notice:</strong></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Maven project examples aren't available in JBDS. </p><p>Pure Maven project examples are available in JBoss Tools 3.2.0.GA. </p><p>Project examples of the <strong>archetype</strong> type will be available in JBoss Tools 3.3.0.M1.</p><p>Project examples that use a project from a Git/SVN repository aren't implemented yet.</p></div>
<div style="background-color: #f4f4f4; padding: 10px; margin-top: 20px;">
<p style="margin: 0;">Comment by <a href="http://community.jboss.org/docs/DOC-16578">going to Community</a></p>
<p style="margin: 0;">Create a new document in JBoss Tools at <a href="http://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2128">Community</a></p>
</div></td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
</div>
</body>
</html>