-
Notifications
You must be signed in to change notification settings - Fork 12
/
important-apis.html
288 lines (288 loc) · 17.3 KB
/
important-apis.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
<html>
<head>
<meta charset="utf-8">
<title>Forge | Important APIs</title>
<meta content="width=device-width, initial-scale=1.0" name="viewport">
<style>
body {
padding-top: 60px;
}
</style>
<script src="//cdnjs.cloudflare.com/ajax/libs/jquery/1.7.1/jquery.min.js" type="text/javascript"></script>
<link href="/images/favicon.ico" rel="icon">
<link href="/stylesheets/styles.css" rel="stylesheet" type="text/css">
<link href="/stylesheets/bootstrap-responsive.min.css" rel="stylesheet" type="text/css">
<link href="/stylesheets/prettify.css" rel="stylesheet" type="text/css">
<!--[if lt IE 9]>
<script src="//html5shim.googlecode.com/svn/trunk/html5.js" type="text/javascript"></script>
<![endif]-->
<script src="/javascripts/bootstrap.min.js" type="text/javascript"></script>
<script src="/javascripts/bootstrap-collapse.js" type="text/javascript"></script>
<script src="/javascripts/prettify.js" type="text/javascript"></script>
<script src="/javascripts/videoscale.js" type="text/javascript"></script>
<script>
$(document).ready(function() {
$("pre.prettyprint code").removeClass("prettyprint").removeClass("linenums");
prettyPrint();
});
</script>
<script>
$(document).ready(function() {
var pathname = window.location.pathname;
console.log(pathname);
$("body > .navbar a[href='" + pathname + "']").closest("li").addClass("active");
$("body > #content ul.nav a[href='" + pathname + "#content']").closest("li").addClass("active");
});
</script>
</head>
<body>
<div class="navbar navbar-fixed-top">
<div class="navbar-inner">
<div class="container">
<div class="github-banner hidden-phone hidden-tablet">
<a href="https://github.com/forge/core">
<img alt="Fork me on GitHub" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" style="position:absolute;top:0;right:0;border:0;">
</a>
</div>
<a class="btn btn-navbar" data-target=".nav-collapse" data-toggle="collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
<a class="brand" href="/index.html">
<img alt="JBoss Forge" class="forge-logo" src="/images/jbossforge_icon_256px.png">
</a>
<div class="nav-collapse">
<ul class="nav">
<li>
<a href="/index.html">Home</a>
</li>
<li>
<a href="https://github.com/forge/core#jboss-forge-20">Forge 2</a>
</li>
<li>
<a href="/docs/index.html">Documentation</a>
</li>
<li>
<a href="/team.html">Team</a>
</li>
<li>
<a href="https://community.jboss.org/en/forge">Forums</a>
</li>
<li>
<a href="https://github.com/forge/core">Source</a>
</li>
<li>
<a href="/plugins.html">Plugins</a>
</li>
<li>
<a href="https://issues.jboss.org/browse/FORGE" target="issue tracker">Issue Tracker</a>
</li>
<li>
<a href="https://issues.jboss.org/browse/FORGE#selectedTab=com.atlassian.jira.plugin.system.project%3Aroadmap-panel" target="roadmap">Roadmap</a>
</li>
<li>
<a href="/events.html">Events</a>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="container" id="content">
<div class="container">
<div class="row">
<div class="span3">
<ul class="nav nav-list">
<li class="nav-header">Using Forge</li>
<li>
<a href="/docs/using/#content">Installation</a>
</li>
<li>
<a href="/docs/using/installing-new-plugins.html#content">Installing new Plugins</a>
</li>
<li>
<a href="/docs/using/basic-javaee-app.html#content">Writing Basic Java EE App</a>
</li>
<li>
<a href="/docs/using/samples.html#content">Samples</a>
</li>
<li>
<a href="/docs/using/configure-proxy.html#content">Configure HTTP Proxy</a>
</li>
<li>
<a href="/docs/using/profiling-forge.html#content">Profiling Forge</a>
</li>
<li>
<a href="/docs/using/debugging-forge.html#content">Debugging Forge</a>
</li>
<li>
<a href="/docs/using/faq.html#content">FAQ</a>
</li>
<li>
<a href="/docs/using/affiliation.html#content">Affiliation</a>
</li>
<li class="nav-header">Get involved</li>
<li>
<a href="/docs/get_involved/contribute.html#content">Contribute or Get Involved</a>
</li>
<li>
<a href="/docs/get_involved/release-guide.html#content">Release Guide</a>
</li>
<li>
<a href="/docs/get_involved/write-docs.html#content">Improve our documentation</a>
</li>
<li class="nav-header">Important plugins</li>
<li>
<a href="/docs/important_plugins/arquillian-testing.html#content">Arquillian Testing</a>
</li>
<li>
<a href="/docs/important_plugins/ui-scaffolding.html#content">UI Scaffolding</a>
</li>
<li class="nav-header">Developing plugins</li>
<li>
<a href="/docs/plugin_development/#content">Developing a plugin</a>
</li>
<li>
<a href="/docs/plugin_development/reference-forge-api.html#content">Reference Forge API</a>
</li>
<li>
<a href="/docs/plugin_development/implement-plugin-interface.html#content">Implement the Plugin interface</a>
</li>
<li>
<a href="/docs/plugin_development/give-your-plugin-name.html#content">Give your Plugin a name</a>
</li>
<li>
<a href="/docs/plugin_development/add-commands-to-plugin.html#content">Add Commands to your Plugin</a>
</li>
<li>
<a href="/docs/plugin_development/add-options-to-command.html#content">Add Options to your Commands</a>
</li>
<li>
<a href="/docs/plugin_development/enable-piping.html#content">Enable Piping between Commands</a>
</li>
<li>
<a href="/docs/plugin_development/facets.html#content">Enable modular functionality with Facets</a>
</li>
<li>
<a href="/docs/plugin_development/test-plugins.html#content">Test your Plugin</a>
</li>
<li>
<a href="/docs/plugin_development/reference-libraries.html#content">Reference Libraries</a>
</li>
<li>
<a href="/docs/plugin_development/make-plugin-available.html#content">Make your Plugin available to Forge</a>
</li>
<li>
<a href="/docs/plugin_development/add-plugin-cpi.html#content">Add your Plugin to the Central Plugin Index</a>
</li>
<li>
<a href="/docs/plugin_development/important-apis.html#content">Important APIs</a>
</li>
<li>
<a href="/docs/plugin_development/configure-plugin-repo.html#content">Configure a plugin repository for Forge</a>
</li>
</ul>
</div>
<div class="span9">
<h1>Important APIs</h1>
<h2>Dependency Facet</h2>
<p>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 <span class="caps">POM</span> by copy pasting from some website. Make installing a framework easier by letting Forge do the <span class="caps">POM</span> work for the user. </p>
<h3>Creating dependencies</h3>
<p>Dependencies can easily be created using the DependencyBuilder.</p>
<pre class="prettyprint linenums"><code class="prettyprint linenums">Dependency dep = DependencyBuilder.create()
 .setGroupId("my.group.id")
 .setArtifactId("artifact-id")
 .setVersion("1.0")
 .setScopeType(ScopeType.PROVIDED);</code></pre>
<p>The Dependency class is also input for many other Forge APIs.</p>
<h3>Prompting for versions</h3>
<p>Of course it’s a bad idea to couple your plugin directly to a specific version of the Maven dependency. To let the user choose a version Forge can list all available versions in the repository and prompt the user.</p>
<pre class="prettyprint linenums"><code class="prettyprint linenums">DependencyFacet dependencyFacet = project.getFacet(DependencyFacet.class);
Dependency myDep = DependencyBuilder.create()
 .setGroupId("commons-httpclient")
 .setArtifactId("commons-httpclient");
List<Dependency> versions = dependencyFacet.resolveAvailableVersions(myDep);
Dependency dependency = shell.promptChoiceTyped("What version do you want to install?", versions);</code></pre>
<p>You can also limit the versions using a range:</p>
<pre class="prettyprint linenums"><code class="prettyprint linenums">dependencyFacet.resolveAvailableVersions("org.jboss.forge:example:[1.0.0,)");</code>

<code class="prettyprint linenums">dependencyFacet.resolveAvailableVersions("org.jboss.forge:example:(1.0.0,3.0.0]");</code></pre>
<h3>Adding a dependency to the <span class="caps">POM</span></h3>
<p>Now that we have our dependency we can add it to the <span class="caps">POM</span> file. Maven supports different ways to work with plugin; you can either have <em>managed</em> dependencies or <em>direct</em> dependencies. Managed dependencies are an indirection where you specify the version of a dependency in the parent <span class="caps">POM</span>. For multi-module projects this is often preferred. Forge can do both however.</p>
<pre class="prettyprint linenums"><code class="prettyprint linenums">dependencyFacet.addDirectDependency(Dependency dep);
dependencyFacet.addManagedDependency(Dependency dep);</code></pre>
<h2>Maven Plugin Facet</h2>
<p>A little more advanced is creating Maven Plugin configuration from your plugin.<br />
First of all your plugin needs the forge-maven-api.</p>
<pre class="prettyprint linenums"><code class="prettyprint linenums"><dependency>
 <groupId>org.jboss.forge</groupId>
 <artifactId>forge-maven-api</artifactId>
 <version>${forge.version}</version>
 <scope>provided</scope>
</dependency></code></pre>
<h3>Creating a plugin</h3>
<p>Now let’s start building the plugin. You use the MavenPluginBuilder for this. First of all a plugin needs a dependency (group id and artifact id).</p>
<pre class="prettyprint linenums"><code class="prettyprint linenums">DependencyBuilder findbugsDependencyBuilder = DependencyBuilder.create()
 .setGroupId("org.codehaus.mojo")
 .setArtifactId("findbugs-maven-plugin");</code>

<code class="prettyprint linenums">MavenPluginBuilder findbugsPlugin = MavenPluginBuilder.create()
 .setDependency(findbugsDependency)</code></pre>
<h3>Add a plugin to the <span class="caps">POM</span></h3>
<p>After building a plugin you can add it to the <span class="caps">POM</span>.</p>
<pre class="prettyprint linenums"><code class="prettyprint linenums">MavenPluginFacet pluginFacet = project.getFacet(MavenPluginFacet.class);
pluginFacet.addPlugin(findbugsPlugin);</code></pre>
<h3>Plugin Configuration</h3>
<p>Most Maven plugins need some kind of configuration. Each configuration element is also a <span class="caps">XML</span> element in the <span class="caps">POM</span> and can potentialy be deeply nested. This makes the <span class="caps">API</span> a little tricky to work with, so try to make small steps.</p>
<p>So for example, let’s add a xmlOutput configuration element to the plugin.</p>
<pre class="prettyprint linenums"><code class="prettyprint linenums">MavenPluginBuilder findbugsPlugin = MavenPluginBuilder.create()
 .setDependency(findbugsDependency)
 .createConfiguration()
 .createConfigurationElement("xmlOutput")
 .setText("true").getParentPluginConfig().getOrigin();</code></pre>
<h2>Resource Facet</h2>
<p>The Resource Facet gives access to resources (files) in a project. It understands the Maven directory structure (e.g. src/test/resources).</p>
<pre class="prettyprint linenums"><code class="prettyprint linenums">FileResource<?> resource = (FileResource<?>) resources.getTestResourceFolder().getChild("example.xml");</code>

<code class="prettyprint linenums">resource.setContents("new string");</code></pre>
<h2><span class="caps">XML</span> parsing and generation</h2>
<p>Many plugins will have to read/write <span class="caps">XML</span> files (e.g. to generate configuration files). Forge has a convenient <span class="caps">XML</span> <span class="caps">API</span>.</p>
<pre class="prettyprint linenums"><code class="prettyprint linenums">Node xml = XMLParser.parse(resource.getResourceInputStream());
Node config = xml.getOrCreate("someelement");
config.createChild("sub").createChild("property@name=test").text("hello");</code>

<code class="prettyprint linenums">resource.setContents(XMLParser.toXMLString(xml));</code></pre>
<p>This will result in the following <span class="caps">XML</span>:</p>
<pre class="prettyprint linenums"><code class="prettyprint linenums"><someelement>
 <sub>
 <property name="test">hello</property>
 </sub>
</someelement></code>
</pre>
</div>
</div>
</div>
<hr>
<footer>
<p>© JBoss 2014</p>
</footer>
</div>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount','UA-34467975-1']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
<script src="http://www.redhat.com/j/elqNow/elqCfg.js" type="text/javascript"></script>
<script src="http://www.redhat.com/j/elqNow/elqImg.js" type="text/javascript"></script>
<div id="oTags">
<script src="http://www.redhat.com/j/s_code.js" type="text/javascript"></script>
<script>
var coreUrl = encodeURI(document.URL.split("?")[0]);
var urlSplit = coreUrl.toLowerCase().split(/\//);
var urlLast = urlSplit[urlSplit.length-1];
var pageNameString = "";
var siteName = "";
var minorSectionIndex = 3
if (urlLast == "") {
urlSplit.splice(-1,1);
}
if (urlLast.search(/\./) >= 0) {
if (urlLast == "index.html") {
urlSplit.splice(-1,1);
}
else {
urlSplit[urlSplit.length-1] = urlLast.split(".").splice(0,1);
}
}
siteName = urlSplit[2].split(".")[1];
s.prop14 = s.eVar27 = siteName || "";
s.prop15 = s.eVar28 = urlSplit[minorSectionIndex] || "";
s.prop16 = s.eVar29 = urlSplit[minorSectionIndex+1] || "";
pageNameString = urlSplit.splice(3).join(" | ");
s.pageName = "jboss | community | " + siteName + " | " + pageNameString;
s.channel = "jboss | community";
s.prop4 = s.eVar23 = encodeURI(document.URL);
s.prop21 = s.eVar18 = coreUrl;
s.prop2 = s.eVar22 = "en";
s.prop3 = s.eVar19 = "us";
</script>
<script src="http://www.redhat.com/j/rh_omni_footer.js" type="text/javascript"></script>
<script language="JavaScript" type="text/javascript">
if(navigator.appVersion.indexOf('MSIE')>=0)document.write(unescape('%3C')+'\!-'+'-')
</script>
<noscript>
<a href="http://www.omniture.com" title="Web Analytics">
<img alt="" border="0" height="1" src="https://smtrcs.redhat.com/b/ss/redhatcom,redhatglobal/1/H.25.4--NS/0?[AQB]&cdp=3&[AQE]" width="1">
</a>
</noscript>
</div>
</body>
</html>