forked from vert-x/vert-x.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathembedding_manual.html
196 lines (179 loc) · 11.9 KB
/
embedding_manual.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
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<link href='http://fonts.googleapis.com/css?family=Lato' rel='stylesheet' type='text/css'>
<!-- <link rel="stylesheet/less" href="bootstrap/less/bootstrap.less">
<script src="bootstrap/less/less-1.3.3.min.js"></script>
-->
<link href="bootstrap/bootstrap.css" type="text/css" rel="stylesheet"/>
<link href="google-code-prettify/prettify.css" type="text/css" rel="stylesheet"/>
<script type="text/javascript" src="google-code-prettify/prettify.js"></script>
<link href="css/vertx.css" type="text/css" rel="stylesheet"/>
<link href="css/sunburst.css" type="text/css" rel="stylesheet"/>
<title>Vert.x</title>
<script>
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-30144458-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>
</head>
<body onload="prettyPrint()" class="hp">
<div class="navbar navbar-fixed-top">
<div class="navbar-inner">
<div class="container">
<a class="btn btn-navbar" data-toggle="collapse"
data-target=".nav-collapse">
<span class="i-bar"></span>
<span class="i-bar"></span>
<span class="i-bar"></span>
</a>
<a class="brand" href="/">Vert.x</a>
<div class="nav-collapse">
<ul class="nav">
<li><a href="/">Home</a></li>
<li><a href="downloads.html">Download</a></li>
<li><a href="install.html">Install</a></li>
<li><a href="docs.html">Documentation</a></li>
<li><a href="examples.html">Examples</a></li>
<li><a href="community.html">Project Info</a></li>
<li><a href="https://github.com/vert-x/vert.x">Github</a></li>
<li><a href="http://modulereg.vertx.io/">Module Registry</a></li>
<li><a href="http://groups.google.com/group/vertx">Google Group</a></li>
<li><a href="http://vertxproject.wordpress.com/">Blog</a></li>
</ul>
</div>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="span12">
<div class="well">
<h1>Embedding Vert.x</h1>
</div>
</div>
</div>
<div class="row">
<div class="span12">
<div class="well">
<div>
<div class="toc">
<ul>
<li><a href="#embedding-the-vertx-platform">Embedding the Vert.x platform</a><ul>
<li><a href="#required-jars">Required jars</a></li>
<li><a href="#system-properties">System Properties</a></li>
<li><a href="#config-files">Config files</a><ul>
<li><a href="#file-langsproperties">File langs.properties</a></li>
<li><a href="#file-clusterxml">File cluster.xml</a></li>
<li><a href="#file-repostxt">File repos.txt</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#embedding-vertx-core">Embedding Vert.x core</a><ul>
<li><a href="#required-jars_1">Required jars</a></li>
<li><a href="#core-thread-safety">Core thread safety</a><ul>
<li><a href="#event-loops-and-scaling-vertx-embedded">Event loops and scaling Vert.x embedded</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<p>It's highly recommended that you run Vert.x applications as modules using the <code>vertx runmod</code> command at the command line, however it is possible to embed Vert.x inside pre-existing Java applications. There are two ways this can be done:</p>
<h1 id="embedding-the-vertx-platform">Embedding the Vert.x platform</h1><br/>
<p>The Vert.x platform is the container which knows how to run Vert.x modules and verticles, it also contains the Vert.x module system.</p>
<p>You use an instance of the interface <code>org.vertx.java.platform.PlatformManager</code> to control the platform.</p>
<p>To get an instance of <code>PlatformManager</code> you use the <code>org.vertx.java.platform.PlatformLocator</code> class:</p>
<pre class="prettyprint">PlatformManager pm = PlatformLocator.factory.createPlatformManager();
</pre>
<p>Once you have an instance of <code>PlatformManager</code> you can deploy and undeploy modules and verticles, install modules and various other actions. See the JavaDoc for more information on the available methods.</p>
<p>Here's an example:</p>
<p>Deploy 10 instances of a module passing in some config</p>
<pre class="prettyprint">JsonObject conf = new JsonObject().putString("foo", "wibble");
pm.deployModule("com.mycompany~my-module~1.0", conf, 10, new AsyncResultHandler<String>() {
public void handle(AsyncResult<String> asyncResult) {
if (asyncResult.succeeded()) {
System.out.println("Deployment ID is " + asyncResult.result());
} else {
asyncResult.cause().printStackTrace();
}
}
});
</pre>
<p>The methods available on <code>PlatformManager</code> roughly map to the actions performed by the <code>vertx</code> command at the command line.</p>
<h2 id="required-jars">Required jars</h2><br/>
<p>To embed the Vert.x platform you will need all the jars from the Vert.x install <code>lib</code> directory on your classpath. You won't need the hazelcast jar if you aren't using clustering.</p>
<h2 id="system-properties">System Properties</h2><br/>
<p>When using the platform manager the following system properties can be set:</p>
<ul>
<li><code>vertx.home</code> - When installing system modules, vert.x will install them in a directory <code>sys-mods</code> which is in the directory given by this property.</li>
<li><code>vertx.mods</code> - When looking for or installing non system modules Vert.x will look in the directory <code>mods</code> in the current working directory. If this property is set this will tell Vert.x to instead look in the provided directory.</li>
<li><code>vertx.clusterManagerFactory</code> - If you're using clustering this property should contain the fully qualified class name of the cluster manager factory that you want to use. If you are just using he default Hazelcast cluster manager factory the value should be <code>org.vertx.java.spi.cluster.impl.hazelcast.HazelcastClusterManagerFactory</code>.</li>
</ul>
<h2 id="config-files">Config files</h2><br/>
<p>The Vert.x platform will look for various config files on the classpath. The vert.x platform .jar contains the default files inside it, but if you want to override any settings you can provide your own versions - just make sure you put them on the classpath ahead of the vert.x platform jar.</p>
<h3 id="file-langsproperties">File <code>langs.properties</code></h3><br/>
<p>This config file tells Vert.x which modules contain the language implementations for particular languages. It's described in the <a href="language_support.html">Support a New Language Guide</a></p>
<h3 id="file-clusterxml">File <code>cluster.xml</code></h3><br/>
<p>This configures Hazelcast clustering. It's described in the <a href="manual.html">main manual</a>.</p>
<h3 id="file-repostxt">File <code>repos.txt</code></h3><br/>
<p>This configures which repositories the Vert.x module system will look in for modules. It's described in the <a href="mods_manual.html">modules manual</a>.</p>
<h1 id="embedding-vertx-core">Embedding Vert.x core</h1><br/>
<p><strong><em> Please note this feature is intended for power users only. </em></strong></p>
<p>It's also possible to embed the Vert.x core classes directly and bypass the Vert.x platform altogether.</p>
<p>If you are embedding this way you should be aware that</p>
<ul>
<li>You will only be able to use Vert.x with Java, not any of the other languages that Vert.x suppports.</li>
<li>You will not have access to the Vert.x module system so you will not be able to easily benefit from functionality provided by the community in the form of modules.</li>
<li>You will not benefit from the automatic compilation of Java verticles at run-time. You will have to compile your classes manually.</li>
<li>You will have to manage scaling of your application manually by programmatically creating more instances of your servers. You will not be able to benefit from the <code>-instances</code> option of the <code>vertx</code> command or in the <code>PlatformManager</code> API.</li>
<li>You will need to manually ensure you do not have concurrent access to non thread-safe core objects in your application. The Vert.x platform would normally protect you against this.</li>
</ul>
<p>If you are happy with the above limitations then Vert.x can be used directly in a Java application as the following echo server example demonstrates</p>
<pre class="prettyprint">public class Embedded {
public static void main(String[] args) throws Exception {
Vertx vertx = VertxFactory.newVertx();
// Create an echo server
vertx.createNetServer().connectHandler(new Handler<NetSocket>() {
public void handle(final NetSocket socket) {
Pump.createPump(socket, socket).start();
}
}).listen(1234);
// Prevent the JVM from exiting
System.in.read();
}
}
</pre>
<p>You first get a reference to the <code>Vertx</code> object using the <code>VertxFactory</code> class, then you use the core classes as you wish.</p>
<p>Note that all Vert.x threads are daemon threads and they will <em>not</em> prevent the JVM for exiting. Therefore you must ensure that the <code>main()</code> method does not run to completion, e.g. in this example we have used <code>System.in.read()</code> to block the main thread waiting for IO from the console.</p>
<h2 id="required-jars_1">Required jars</h2><br/>
<p>To embed the Vert.x platform you will need all the jars from the Vert.x install lib directory apart from <code>vertx-platform-*.jar</code> on your classpath. You won't need the hazelcast jar if you aren't using clustering.</p>
<h2 id="core-thread-safety">Core thread safety</h2><br/>
<p>Many of the Vert.x core classes are <em>not</em> thread-safe. When running Vert.x in the Vert.x platform you don't have to worry about that as Vert.x guarantees that your verticle code is never executed by more than one thread concurrently.</p>
<p>When running core embedded you have to be more careful as there is no container to make such guarantees. Therefore it's up to you the developer to guard against concurrent access to non thread-safe classes.</p>
<p>Please consult the JavaDoc to see which classes are thread-safe and which are not.</p>
<h3 id="event-loops-and-scaling-vertx-embedded">Event loops and scaling Vert.x embedded</h3><br/>
<p>When running your Vert.x code in a standard verticle, Vert.x ensures it's all executed by the exact same thread (event loop).</p>
<p>When running Vert.x embedded you will start off on one of your own application threads which won't be a Vert.x event loop. When Vert.x calls the handlers of any of the core objects that you create, they <em>will</em> be called on an event loop.</p>
<p>Vert.x determines which event loops to use according to the following rules:</p>
<p>If the calling thread is not an event loop then:</p>
<ul>
<li>Instances of <code>NetServer</code>, <code>NetClient</code>, <code>HttpServer</code> and <code>HttpClient</code> will be assigned an event loop when they are created. When any of their handlers are subsequently called they will be called using that event loop.</li>
<li>When a handler is registered on the event bus an event loop will be assigned to it. This event loop will then be used every time the handler is called.</li>
<li>File system operation handlers are called using an event loop determined by Vert.x</li>
</ul>
<p>If the calling thread is an event loop, then that current event loop will be used.</p>
<p>Since a particular instance of <code>NetServer</code>, <code>HttpServer</code> will have all their handlers executed on the same event loop, if you want to scale your servers across multiple cores you need to create multiple instances of them, from a thread that is not an event loop.</p></div>
</div>
</div>
</div>
</div>
</body>
</html>