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
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
|
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Chapter 4. Migration Guide</title><link rel="stylesheet" href="html.css" type="text/css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.74.0"><link rel="home" href="index.html" title="Red5 - Reference Documentation"><link rel="up" href="getting-started.html" title="Part I. Getting Started"><link rel="prev" href="configuration-files.html" title="Chapter 3. Configuration Files"><link rel="next" href="libraries.html" title="Chapter 5. Red5 Libraries"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div xmlns="http://www.w3.org/TR/xhtml1/transitional" style="background-color:white;border:none;height:73px;border:1px solid black;"><a style="border:none;" href="http://osflash.org/red5" title="Red5 Open Source Flash Server"><img style="border:none;" src="images/red5-banner.png"></img></a><a style="border:none;" href="http://osflash.org/red5" title="Red5 Open Source Flash Server"><img style="border:none;position:absolute;padding-top:5px;right:42px;" src="images/red5-banner-logo.png"></img></a></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="migration-guide"></a>Chapter 4. Migration Guide</h2></div></div></div><p>This document describes API differences between the Macromedia Flash Communication
Server / Adobe Flash Media Server and Red5. It aims at helping migrate existing
applications to Red5. </p><p>If you don't have an application in Red5 yet, please read the tutorial about howto create
new applications first. </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1362"></a>4.1. Application callbacks</h2></div></div></div><p>When implementing serverside applications, one of the most important functionalities is to
get notified about clients that connect or disconnect and to be informed about the creation
of new instances of the application. </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1367"></a>4.1.1. Interface IScopeHandler</h3></div></div></div><p>Red5 specifies these actions in the interface IScopeHandler
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/api/IScopeHandler.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/IScopeHandler.html</a>. See the API documentation for further details.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1375"></a>4.1.2. Class ApplicationAdapter</h3></div></div></div><p>As some methods may be called multiple times for one request (e.g. connect will be called
once for every scope in the tree the client connects to), the class ApplicationAdapter
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html</a> defines
additional methods.
</p><p>This class usually is used as base class for new applications. </p><p>Here is a short overview of methods of the FCS / FMS application class and their
corresponding methods of ApplicationAdapter
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html</a> in Red5:
</p><div class="table"><a name="fms-red5-migration"></a><p class="title"><b>Table 4.1. FMS to Red5 Callback Methods</b></p><div class="table-contents"><table summary="FMS to Red5 Callback Methods" border="0"><colgroup><col><col></colgroup><tbody><tr><td>onAppStart</td><td>appStart / roomStart</td></tr><tr><td>onAppStop</td><td>appStop / roomStop</td></tr><tr><td>onConnect</td><td>appConnect / roomConnect / appJoin / roomJoin</td></tr><tr><td>onDisconnect</td><td>appDisconnect / roomDisconnect / appLeave / roomLeave</td></tr></tbody></table></div></div><br class="table-break"><p>The app''' methods are called for the main application, the room''' methods are called for
rooms (i.e. instances) of the application. </p><p>You can also also use the ApplicationAdapter
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html</a> to check for streams, shared objects, or subscribe
them. See the API documentation for further details.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e1424"></a>4.1.2.1. Execution order of connection methods</h4></div></div></div><p>Assuming you connect to rtmp://server/app/room1/room2 </p><p>At first, the connection is established, so the user "connects" to all scopes that are
traversed up to room2: </p><div class="orderedlist"><ol type="1"><li><p>app (-> appConnect)</p></li><li><p>room1 (-> roomConnect) </p></li><li><p>room2 (-> roomConnect) </p></li></ol></div><p>After the connection is established, the client object is retrieved and if it's the first
connection by this client to the scope, he "joins" the scopes: </p><div class="orderedlist"><ol type="1"><li><p>app (-> appJoin)</p></li><li><p>room1 (-> roomJoin)</p></li><li><p>room2 (-> roomJoin)</p></li></ol></div><p>If the same client establishes a second connection to the same scope, only the connect
methods will be called. If you conect to partially the same scopes, only a few join methods
might be called, e.g. rtmp://server/app/room1/room3 will trigger </p><div class="orderedlist"><ol type="1"><li><p>appConnect("app") </p></li><li><p>joinConnect("room1") </p></li><li><p>joinConnect("room3") </p></li><li><p>roomJoin("room3")</p></li></ol></div><p>The appStart method currently is only called once during startup of Red5 as it currently
can't unload/load applications like FCS/FMS does. The roomStart methods are called when
the first client connects to a room. </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1470"></a>4.1.3. Accepting / rejecting clients</h3></div></div></div><p>FCS / FMS provide the methods acceptConnection and rejectConnection to accept and
reject new clients. To allow clients to connect, no special action is required by Red5
applications, the *Connect methods just need to return true in this case. </p><p>If a client should not be allowed to connect, the method rejectClient can be called which is
implemented by the ApplicationAdapter
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html</a> class. Any parameter passed to rejectClient is available
as the application property of the status object that is returned to the caller.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1480"></a>4.2. Current connection and client</h2></div></div></div><p>Red5 supports two different ways to access the current connection from an invoked
method. The connection can be used to get the active client and the scope he is connected
to. The first possibility uses the "magic" Red5
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/api/Red5.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/Red5.html</a> object:
</p><pre class="programlisting">
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.IClient;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.IConnection;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.IScope;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.Red5;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">public</font> <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">void</font> whoami() {
IConnection conn = Red5.getConnectionLocal();
IClient client = conn.getClient();
IScope scope = conn.getScope();
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// ... </font>
}
</pre><p>The second possiblity requires the method to be defined with an argument of type
IConnection
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/api/IConnection.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/IConnection.html</a> as
implicit first parameter which is automatically added by Red5 when a client calls the
method:
</p><pre class="programlisting">
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.IClient;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.IConnection;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.IScope;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">public</font> <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">void</font> whoami(IConnection conn) {
IClient client = conn.getClient();
IScope scope = conn.getScope();
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// ... </font>
}
</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1497"></a>4.3. Additional handlers</h2></div></div></div><p>For many applications, existing classes containing application logic that is not related to
Red5 are required to be reused. In order to make them available for clients connecting
through RTMP, these classes need to be registered as handlers in Red5. </p><p>There are currently two ways to register these handlers: </p><div class="orderedlist"><ol type="1"><li><p>By adding them to the configuration files.</p></li><li><p>By registering them manually from the application code. </p></li></ol></div><p>The handlers can be executed by clients with code similar to this:</p><div class="literallayout"><p><br>
nc = new NetConnection(); <br>
nc.connect("rtmp://localhost/myapp"); <br>
nc.call("handler.method", nc, "Hello world!"); <br>
</p></div><p>If a handler is requested, Red5 always looks it up in the custom scope handlers before
checking the handlers that have been set up in the context through the configuration file. </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="MigrationGuideHandlersinconfigurationfiles"></a>4.3.1. Handlers in configuration files</h3></div></div></div><p>This method is best suited for handlers that are common to all scopes the application runs
in and that don't need to change during the lifetime of an application. </p><p>To register the class com.fancycode.red5.HandlerSample as handler sample, the following
bean needs to be added to WEB-INF/red5-web.xml:</p><pre class="programlisting">
<b class="hl-tag" style="color: blue"><bean</b> <span class="hl-attribute" style="color: blue">id</span>=<span class="hl-value" style="color: blue">"sample.service"</span>
<span class="hl-attribute" style="color: blue">class</span>=<span class="hl-value" style="color: blue">"com.fancycode.red5.HandlerSample"</span>
<span class="hl-attribute" style="color: blue">singleton</span>=<span class="hl-value" style="color: blue">"true"</span><b class="hl-tag" style="color: blue"> /></b>
</pre><p>Note that the id of the bean is constructed as the name of the handler (here sample) and
the keyword service. </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1528"></a>4.3.2. Handlers from application code</h3></div></div></div><p>All applications that use handlers which are different for the various scopes or want to
change handlers, need a way to register them from the serverside code. These handlers
always override the handlers configured in red5-web.xml. The methods required for
registration are described in the interface IServiceHandlerProvider
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/api/service/IServiceHandlerProvider.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/service/IServiceHandlerProvider.html</a> which is implemented
by ApplicationAdapter
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html</a>.
</p><p>The same class as above can be registered using this code: </p><pre class="programlisting">
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">public</font> <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">boolean</font> appStart(IScope app) {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">if</font> (!<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">super</font>.appStart(scope))
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">return</font> false;
Object handler = <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">new</font> com.fancycode.red5.HandlerSample();
app.registerServiceHandler(<b class="hl-string"><i style="color:red">"sample"</i></b>, handler);
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">return</font> true;
}
</pre><p>Note that in this example, only the application scope has the sample handler but not the
subscopes! If the handler should be available in the rooms as well, it must be registered in
roomStart for the room scopes.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1545"></a>4.4. Calls to client methods</h2></div></div></div><p>To call methods from your Red5 application on the client, you will first need a reference to
the current connection object: </p><pre class="programlisting">
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.IConnection;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.Red5;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.service.IServiceCapableConnection;
...
IConnection conn = Red5.getConnectionLocal();
</pre><p>If the connection implements the IServiceCapableConnection
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/api/service/IServiceCapableConnection.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/service/IServiceCapableConnection.html</a> interface, it supports
calling methods on the other end:
</p><pre class="programlisting">
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">if</font> (conn <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">instanceof</font> IServiceCapableConnection) {
IServiceCapableConnection sc = (IServiceCapableConnection) conn;
sc.invoke(<b class="hl-string"><i style="color:red">"the_method"</i></b>, <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">new</font> Object[]{<b class="hl-string"><i style="color:red">"One"</i></b>, 1});
}
</pre><p>If you need the result of the method call, you must provide a class that implements the
IPendingServiceCallback
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/api/service/IPendingServiceCallback.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/service/IPendingServiceCallback.html</a> interface:
</p><pre class="programlisting">
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.service.IPendingService;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.service.IPendingServiceCallback;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">class</font> MyCallback <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">implements</font> IPendingServiceCallback {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">public</font> <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">void</font> resultReceived(IPendingServiceCall call) {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// Do something with "call.getResult()" </font>
}
}
</pre><p>The method call looks now like this: </p><pre class="programlisting">
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">if</font> (conn <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">instanceof</font> IServiceCapableConnection) {
IServiceCapableConnection sc = (IServiceCapableConnection) conn;
sc.invoke(<b class="hl-string"><i style="color:red">"the_method"</i></b>, <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">new</font> Object[]{<b class="hl-string"><i style="color:red">"One"</i></b>, 1}, <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">new</font> MyCallback());
}
</pre><p>Of course you can implement this interface in your application and pass a reference to the
application instance.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1572"></a>4.5. SharedObjects</h2></div></div></div><p>The methods to access shared objects from an application are specified in the interface
ISharedObjectService
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/api/so/ISharedObjectService.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/so/ISharedObjectService.html</a>.
</p><p>When dealing with shared objects in serverside scripts, special care must be taken about
the scope they are created in. </p><p>To create a new shared object when a room is created, you can override the method
roomStart in your application: </p><pre class="programlisting">
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.adapter.ApplicationAdapter;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.IScope;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.so.ISharedObject;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">public</font> <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">class</font> SampleApplication <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">extends</font> ApplicationAdapter {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">public</font> <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">boolean</font> roomStart(IScope room) {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">if</font> (!<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">super</font>.roomStart(room))
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">return</font> false;
createSharedObject(room, <b class="hl-string"><i style="color:red">"sampleSO"</i></b>, true);
ISharedObject so = getSharedObject(room, <b class="hl-string"><i style="color:red">"sampleSO"</i></b>);
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// Now you could do something with the shared object... </font>
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">return</font> true;
}
}
</pre><p>Now everytime a first user connects to a room of a application, e.g. through rtmp://server/application/room1, a shared object sampleSO is created by the server. </p><p>If a shared object should be created for connections to the main application, e.g. rtmp://server/application, the same must be done in the method appStart. </p><p>For further informations about the possible methods a shared object provides please refer
to the api documentation of the interface ISharedObject
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/api/so/ISharedObject.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/so/ISharedObject.html</a>.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1595"></a>4.5.1. Serverside change listeners</h3></div></div></div><p>To get notified about changes of the shared object similar to onSync in FCS / FMS, a
listener must implement the interface ISharedObjectListener
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/api/so/ISharedObjectListener.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/so/ISharedObjectListener.html</a>:
</p><pre class="programlisting">
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.so.ISharedObject;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.so.ISharedObjectListener;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">public</font> <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">class</font> SampleSharedObjectListener
Migration Guide
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">implements</font> ISharedObjectListener {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">public</font> <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">void</font> onSharedObjectUpdate(ISharedObject so,
String key, Object value) {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// The attribute &lt;key&gt; of the shared object &lt;so&gt; </font>
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// was changed to &lt;value&gt;. </font>
}
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">public</font> <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">void</font> onSharedObjectDelete(ISharedObject so, String key) {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// The attribute &lt;key&gt; of the shared object &lt;so&gt; was deleted. </font>
}
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">public</font> <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">void</font> onSharedObjectSend(ISharedObject so,
String method, List params) {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// The handler &lt;method&gt; of the shared object &lt;so&gt; was called </font>
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// with the parameters &lt;params&gt;. </font>
}
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// Other methods as described in the interface... </font>
}
</pre><p>Additionally, the listener must get registered at the shared object: </p><pre class="programlisting">
ISharedObject so = getSharedObject(scope, <b class="hl-string"><i style="color:red">"sampleSO"</i></b>);
so.addSharedObjectListener(<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">new</font> SampleSharedObjectListener())
</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="MigrationGuideChangingfromapplicationcode"></a>4.5.2. Changing from application code</h3></div></div></div><p>A shared object can be changed by the server as well: </p><pre class="programlisting">
ISharedObject so = getSharedObject(scope, <b class="hl-string"><i style="color:red">"sampleSO"</i></b>);
so.setAttribute(<b class="hl-string"><i style="color:red">"fullname"</i></b>, <b class="hl-string"><i style="color:red">"Sample user"</i></b>);
</pre><p>Here all subscribed clients as well as the registered handlers are notified about the new /
changed attribute. </p><p>If multiple actions on a shared object should be combined in one update event to the
subscribed clients, the methods beginUpdate and endUpdate must be used: </p><pre class="programlisting">
ISharedObject so = getSharedObject(scope, <b class="hl-string"><i style="color:red">"sampleSO"</i></b>);
so.beginUpdate();
so.setAttribute(<b class="hl-string"><i style="color:red">"One"</i></b>, <b class="hl-string"><i style="color:red">"1"</i></b>);
so.setAttribute(<b class="hl-string"><i style="color:red">"Two"</i></b>, <b class="hl-string"><i style="color:red">"2"</i></b>);
so.removeAttribute(<b class="hl-string"><i style="color:red">"Three"</i></b>);
so.endUpdate();
</pre><p>The serverside listeners will receive their update notifications through separate method
calls as without the beginUpdate and endUpdate.</p><p>Calls to shared object handlers through remote_so.send(<handler>, <args>) from a Flash
client or the corresponding serverside call can be mapped to methods in Red5. Therefore a
handler must get registered through a method of the ISharedObjectHandlerProvider
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/api/so/ISharedObjectHandlerProvider.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/so/ISharedObjectHandlerProvider.html</a>
interface similar to the application handlers:
</p><pre class="programlisting">
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">package</font> com.fancycode.red5;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">class</font> MySharedObjectHandler {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">public</font> <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">void</font> myMethod(String arg1) {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// Now do something </font>
}
}
...
ISharedObject so = getSharedObject(scope, <b class="hl-string"><i style="color:red">"sampleSO"</i></b>);
so.registerServiceHandler(<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">new</font> MySharedObjectHandler());
</pre><p>Handlers with a given name can be registered as well: </p><pre class="programlisting">
ISharedObject so = getSharedObject(scope, <b class="hl-string"><i style="color:red">"sampleSO"</i></b>);
so.registerServiceHandler(<b class="hl-string"><i style="color:red">"one.two"</i></b>, <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">new</font> MySharedObjectHandler());
</pre><p>Here, the method could be called through one.two.myMethod.
Another way to define event handlers for SharedObjects is to add them to the red5-
web.xml similar to the file-based application handlers. The beans must have a name of
<SharedObjectName>.<DottedServiceName>.soservice, so the above example could also
be defined with: </p><pre class="programlisting">
<b class="hl-tag" style="color: blue"><bean</b> <span class="hl-attribute" style="color: blue">id</span>=<span class="hl-value" style="color: blue">"sampleSO.one.two.soservice"</span>
<span class="hl-attribute" style="color: blue">class</span>=<span class="hl-value" style="color: blue">"com.fancycode.red5.MySharedObjectHandler"</span>
<span class="hl-attribute" style="color: blue">singleton</span>=<span class="hl-value" style="color: blue">"true"</span><b class="hl-tag" style="color: blue"> /></b>
</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1639"></a>4.6. Persistence</h2></div></div></div><p>Persistence is used so properties of objects can be used even after the server has been
restarted. In FCS / FMS usually local shared objects on the serverside are used for this. </p><p>Red5 allows arbitrary objects to be persistent, all they need to do is implement the
interface IPersistable
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/api/persistence/IPersistable.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/persistence/IPersistable.html</a>. Basically these objects have a type, a path, a name (all strings) and
know how to serialize and deserialize themselves.
</p><p>Here is a sample of serialization and deserialization: </p><pre class="programlisting">
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> java.io.IOException;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.io.object.Input;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.io.object.Output;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.persistence.IPersistable;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">class</font> MyPersistentObject <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">implements</font> IPersistable {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// Attribute that will be made persistent </font>
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">private</font> String data = <b class="hl-string"><i style="color:red">"My persistent value"</i></b>;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">void</font> serialize(Output output) <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">throws</font> IOException {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// Save the objects's data. </font>
output.writeString(data);
}
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">void</font> deserialize(Input input) <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">throws</font> IOException {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// Load the object's data. </font>
data = input.readString();
}
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// Other methods as described in the interface... </font>
}
</pre><p>To save or load this object, the following code can be used: </p><pre class="programlisting">
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.adapter.ApplicationAdapter;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.IScope;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.Red5;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.persistence.IPersistenceStore;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">class</font> MyApplication <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">extends</font> ApplicationAdapter {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">private</font> <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">void</font> saveObject(MyPersistentObject object) {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// Get current scope. </font>
IScope scope = Red5.getConnectionLocal().getScope();
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// Save object in current scope. </font>
scope.getStore().save(object);
}
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">private</font> <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">void</font> loadObject(MyPersistentObject object) {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// Get current scope. </font>
IScope scope = Red5.getConnectionLocal().getScope();
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// Load object from current scope. </font>
scope.getStore().load(object);
}
}
</pre><p>If no custom objects are required for an application, but data must be stored for future
reuse, it can be added to the IScope
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/api/IScope.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/IScope.html</a> through the interface IAttributeStore
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/api/IAttributeStore.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/IAttributeStore.html</a>. In scopes, all attributes that don't start with
IPersistable.TRANSIENT_PREFIX are persistent.
</p><p>The backend that is used to store objects is configurable. By default persistence in memory
and in the filesystem is available. </p><p>When using filesystem persistence for every object a file is created in "webapps/<app>/
persistence/<type>/<path>/<name>.red5", e.g. for a shared object "theSO" in the
connection to "rtmp://server/myApp/room1" a file at "webapps/myApp/persistence/
SharedObject/room1/theSO.red5" would be created. </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1669"></a>4.7. Periodic events</h2></div></div></div><p>Applications that need to perform tasks regularly can use the setInterval in FCS / FMS to
schedule methods for periodic execution. </p><p>Red5 provides a scheduling service (ISchedulingService
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/api/scheduling/ISchedulingService.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/scheduling/ISchedulingService.html</a>) that is implemented
by ApplicationAdapter
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html</a> like most other services. The service can register an object (which
needs to implement the IScheduledJob
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/api/scheduling/IScheduledJob.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/scheduling/IScheduledJob.html</a> interface) whose execute method is called in a given
interval.
</p><p>To register an object, code like this can be used: </p><pre class="programlisting">
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.IScope;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.IScheduledJob;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.api.ISchedulingService;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.adapter.ApplicationAdapter;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">class</font> MyJob <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">implements</font> IScheduledJob {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">public</font> <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">void</font> execute(ISchedulingService service) {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// Do something </font>
}
}
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">public</font> <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">class</font> SampleApplication <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">extends</font> ApplicationAdapter {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">public</font> <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">boolean</font> roomStart(IScope room) {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">if</font> (!<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">super</font>.roomStart(room))
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">return</font> false;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// Schedule invokation of job every 10 seconds. </font>
String id = addScheduledJob(10000, <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">new</font> MyJob());
room.setAttribute(<b class="hl-string"><i style="color:red">"MyJobId"</i></b>, id);
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">return</font> true;
}
}
</pre><p>The id that is returned by addScheduledJob can be used later to stop execution of the
registered job: </p><pre class="programlisting">
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">public</font> <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">void</font> roomStop(IScope room) {
String id = (String) room.getAttribute(<b class="hl-string"><i style="color:red">"MyJobId"</i></b>);
removeScheduledJob(id);
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">super</font>.roomStop(room);
}
</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1693"></a>4.8. Remoting</h2></div></div></div><p>Remoting can be used by non-rtmp clients to invoke methods in Red5. Another possibility
is to call methods from Red5 to other servers that provide a remoting service. </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1698"></a>4.8.1. Remoting server</h3></div></div></div><p>Services that should be available for clients need to be registered the same way as
additional application handlers are registered. See above for details. </p><p>To enable remoting support for an application, the following section must be added to the
WEB-INF/web.xml file: </p><p>
<span class="bold"><strong>web.xml</strong></span> -
</p><pre class="programlisting">
<b class="hl-tag" style="color: blue"><servlet></b>
<b class="hl-tag" style="color: blue"><servlet-name></b>gateway<b class="hl-tag" style="color: blue"></servlet-name></b>
<b class="hl-tag" style="color: blue"><servlet-class></b>
org.red5.server.net.servlet.AMFGatewayServlet
<b class="hl-tag" style="color: blue"></servlet-class></b>
<b class="hl-tag" style="color: blue"></servlet></b>
<b class="hl-tag" style="color: blue"><servlet-mapping></b>
<b class="hl-tag" style="color: blue"><servlet-name></b>gateway<b class="hl-tag" style="color: blue"></servlet-name></b>
<b class="hl-tag" style="color: blue"><url-pattern></b>/gateway/*<b class="hl-tag" style="color: blue"></url-pattern></b>
<b class="hl-tag" style="color: blue"></servlet-mapping></b>
</pre><p>The path specified in the <url-pattern> tag (here gateway) can be used by the remoting
client as connection url. If this example would have been specified for an application
myApp, the URL would be: </p><div class="literallayout"><p><br>
http://localhost:5080/myApp/gateway <br>
</p></div><p>Methods invoked through this connection will be executed in the context of the application
scope. If the methods should be executed in subscopes, the path to the subscopes must be
added to the URL like: </p><div class="literallayout"><p><br>
http://localhost:5080/myApp/gateway/room1/room2 <br>
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1720"></a>4.8.2. Remoting client</h3></div></div></div><p>The class RemotingClient
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/net/remoting/RemotingClient.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/net/remoting/RemotingClient.html</a> defines all methods that are required to call methods through the
remoting protocol.
</p><p>The following code serves as example about how to use the remoting client:</p><pre class="programlisting">
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.net.remoting.RemotingClient;
String url = <b class="hl-string"><i style="color:red">"http://server/path/to/service"</i></b>;
RemotingClient client = <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">new</font> RemotingClient(url);
Object[] args = <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">new</font> Object[]{<b class="hl-string"><i style="color:red">"Hello world!"</i></b>};
Object result = client.invokeMethod(<b class="hl-string"><i style="color:red">"service.remotingMethod"</i></b>, args);
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// Now do something with the result </font>
</pre><p>By default, a timeout of 30 seconds will be used per call, this can be changed by passing a
second parameter to the constructor defining the maximum timeout in milliseconds. </p><p>The remoting headers AppendToGatewayUrl, ReplaceGatewayUrl and
RequestPersistentHeader are handled automatically by the Red5 remoting client. </p><p>Some methods may take a rather long time on the called server to complete, so it's better
to perform the call asynchronously to avoid blocking a thread in Red5. Therefore an object
that implements the interface IRemotingCallback
<a class="link" href="http://dl.fancycode.com/red5/api/org/red5/server/net/remoting/IRemotingCallback.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/net/remoting/IRemotingCallback.html</a> must be passed as additional parameter:
</p><pre class="programlisting">
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.net.remoting.RemotingClient;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">import</font> org.red5.server.net.remoting.IRemotingCallback;
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">public</font> <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">class</font> CallbackHandler <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">implements</font> IRemotingCallback {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">void</font> errorReceived(RemotingClient client, String method,
Object[] params, Throwable error) {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// An error occurred while performing the remoting call. </font>
}
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">void</font> resultReceived(RemotingClient client, String method,
Object[] params, Object result) {
<font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-style="italic" color="grey">// The result was received from the server. </font>
}
}
String url = <b class="hl-string"><i style="color:red">"http://server/path/to/service"</i></b>;
RemotingClient client = <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">new</font> RemotingClient(url);
Object[] args = <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">new</font> Object[]{<b class="hl-string"><i style="color:red">"Hello world!"</i></b>};
IRemotingCallback callback = <font xmlns="http://www.w3.org/TR/xhtml1/transitional" font-weight="bold" color="blue">new</font> CallbackHandler();
client.invokeMethod(<b class="hl-string"><i style="color:red">"service.remotingMethod"</i></b>, args, callback);
</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1743"></a>4.9. Streams</h2></div></div></div><p>TODO: How can streams be accessed from an application?</p></div></div><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navfooter"><hr></hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="configuration-files.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="libraries.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 3. Configuration Files </td><td width="20%" align="center"><span style="color:white;font-size:90%;"><a href="http://osflash.org/red5" title="Red5">Red5 Open Source Flash Server</a></span></td><td width="40%" align="right" valign="top"> Chapter 5. Red5 Libraries</td></tr></table></div></body></html>
|
