reference.txt

MilGra0.8b for java media server

1. Introduction

	1.1 Overview
	1.2 Features
	1.3 Sytem Requirements
	1.4 Performance
	1.5 License
	1.6 Kind donators

2. Running the server

	2.1 Overview
	2.2 Parameters
	2.3 Admin console
	2.4 Unit test
	2.5 Unit test

3. Programming the server
	
	3.1 Overview
	3.2 IApplication
	3.3 Client class
	3.4 Stream class
	3.5 Wrapper classes
	3.6 InvokeEvent
	3.7 StreamEvent
	3.8 StatusEvent
	3.9 Utilities

4. Development howtos
	
	4.1 How to create a Custom Application?
	4.2 How to embed Milenia in my package?
	4.3 How to recompile Milenia?
	

1. Introduction


	1.1 Overview
	
		Milenia Grafter Server is an open source flash media server that just 
		works. With Milenia you don't have to know dozens of frameworks and 
		tricks to create custom applications, you don't have to read up 
		thousands of lines of configuration xml's to configure your server 
		properly, you don't have to tear your hair off because of magic 
		mistakes and unexpected errors coming from a closed source application, 
		you don't have to wait for the never-coming answers of water-headed 
		corporations, you don't have to pay thousands of dollars/euros for 
		poorly performing enterprise level products. Simplicity was the only 
		keyword during its creation, so i have not implemented any useless 
		features from other flash media server implementations.
		
	
	1.2 Features
	
		Live Audio/Video streaming
		Live Audio/Video recording
		Video on demand ( VP6 and H264 support is coming )
		FLV playback speed set - slow/fast, forward/reverse
		Stream access control based on stream events
		Simple and fast custom application deployment
		Lightweight data communication
		Client mode - you can connect Milenia to any kind of flash media server
		Stream pushing/pulling to/from other servers
		Built-in bandwidth test - bidirectional and accurate
		Sample access enabled
		Admin console
		Stress tester
		Unit tester
	
		Future Features:
		
		Adobe live encoder integration ( 0.9 )
		VP6, H264 capability ( 0.9 )
		RTMPE support ( 1.0 )
		
	
	1.3 System Requirements:
	
		Any system with Java Virtual Machine 1.5
		
	
	1.4 Performance
	
		Under construction.
	
	
	1.5 The license
	
		Milenia Grafter Server is licensed under General Public License v2.
		
		Copyright (c) 2007-2008 by Milan Toth. All rights reserved.
		This program is free software; you can redistribute it and/ormodify it 
		under the terms of the GNU General Public Licenseas published by the 
		Free Software Foundation; either version 2of the License, or ( at your 
		option ) any later version.
		This program is distributed in the hope that it will be useful, but 
		WITHOUT ANY WARRANTY; without even the implied warranty of 
		MERCHANTABILITY	or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 
		General Public License for more details. You should have received a 
		copy of the GNU General Public Licensealong with this program; if not, 
		write to the Free SoftwareFoundation, Inc., 51 Franklin Street, 
		Fifth Floor, Boston, MA 02110-1301, USA.
		
	
	1.6 Kind donators
	
		Apakian Pty.Ltd
		Reinhard & Löw GbR
		
		Thank you guys! :)
		

2. Running the server


	2.1 Overview
	
		Milenia doesn't need installation, since it's one single java jar file, 
		you simply execute it with the java virtual	machine. First you have to 
		be sure that your system has Java Runtime Environment 1.5 or higher. 
		If not, download it from sun. If you have it, simply type
		 
		java -jar milgra.jar
		
		in the command line, and it should show up the version info and the 
		parameter hints.
		
		The basic server package looks like this : 
		
		applications <DIR>
		streams <DIR>
		sources <DIR>
		milgra.jar
		license.txt
		
		"applications" is the default custom application directory for the 
		server.	You have to copy your custom application jars here. 
		"streams" is the default directory for streams, Milenia saves recorded 
		streams here. 
		"sources" contains the sources and the compiled admin application also. 
		"milgra.jar" is the server itself, "license.txt" is the GPL v2 license.
	
	
	2.2 Parameters
		
		start
		
			starts the server on the default port ( 1935 )
		
		stop
		
			stops the server on the default port ( 1935 )
		
		port [number]
		
			sets the listener port to given number
		
		iostep [number]
		
			sets the io process stepping delay in milisecs. Default is 15
		
		iothreads [number]
		
			sets the thread counts of process groups. If your server isn't 
			under a heavy load, or you want other services to run on your 
			machine, one thread is enough. But if you have a multi-processored 
			multi-cored monster, you can start experimenting with this setting 
			and the stress tester. It won't speed up data throughput since only 
			one process can reach the system bus and the sockets at a time, but
			it fastens stream pushing between threads, and data processing also.
		
		streams [directory]
		
			sets the stream directory where milenia stores/reads up streams. 
			The directory will be created under the directory where milgra.jar 
			is.
		
		applications [directory]
		
			sets the custom application directory where milenia looks for 
			custm applications. The directory will be created under the 
			directory where milgra.jar is.
		
		examples:
		
			The following command starts the server listeneing on port 80, 
			with 20 milliseconds of io stepping and with the default stream 
			directory "mystreams"
		
		java -jar milgra.jar start port 80 iostep 20 streams mystreams
		
			The following command stops the server listening on port 80
		
		java -jar milgra.jar stop port 80
		
		For performance tuning you may have to use additional java virtual 
		machine switches, for example,
		
			-server
		
		or if jvm runs out of memory
		
			-Xmn -Xms -Xmx to set memory size.
		
		The following command starts Milenia with default settings with 500 
		megabytes of maximum memory usage.
		
			java -Xmx500M -jar milgra.jar start
			
	
	2.3 Admin Console
	
		To use the admin console, ensure that the server-side admin application 
		( admin.jar ) is under the Milenia's custom application directory, 
		and the server is running. Open admin.swf ( under sources directory by 
		default ) in a web browser having Flash Player 9. 
		
		For the first run type "admin" for both username and password.
		
		Admin application creates a fourth directory called "admin" in 
		Milenia's root for its config file and logs. I recommend to immediately 
		set a new username/password in admin/config.xml, and you may define 
		allowed ip addresses also.
		
		In the console, you will see two main tabs. 
		
		Graphs tab
		
			After a succesful login, you will find yourself at the graphs tab.
			These graphs shows the i/o states of the server. "Bandwidth" shows 
			the overall, incoming, and outgoing bandwidth in Megabits/second. 
			"Connected Clients" shows the overall, passive and active client 
			count on the server. Active clients are the clients created by a 
			custom application to connect to other servers. "Processing Threads" 
			shows socket, client and stream pool processing thread count,
			"Execution Times" show the average process execution times of the 
			different thread pools.
		
		Applications tab
		
			You can check the available applications here. They consists of the
			custom applications under Milenia Grafter Server / applications 
			directory, and the running applications ( if custom application jar 
			has been removed from the directory, but the application hasn't 
			been unloaded ). You can check the status, connected clients and 
			bandwidth info of an application. You can refresh application list 
			any time, this case Milenia will reread the applicaitons directory. 
			You have to wait for the next refresh event to see the new list. 
			You can unload/load applications by pressing load/unload buttons.
			Under applications tab, it will show one connected client ( you ) 
			and one running application ( the admin application ).
			
			I also encourage the use of jconsole if you want to receive really 
			detailed information about your machine and jvm health status.
	
	
	2.4 Unit tester
	
		You can test all of the server's functions with this application, and
		also you can perform stress test on a server with this.
		The other purpose of the stress tester is the API showcase for 
		developers, both server and client side code is well commented, and
		covers all possibilities of Milenia.
		
		Client-Server Connection
		
			Performs various connection tests, tests all possible connection 
			events between the client and the server.
			
		Client-Server Data Communication
		
			Performs Data Exchange tests. Tests invoke calls from client to
			server and back, and tests exchange of AMF0 types.
			
		Client-Server Live Streaming
		
			Performs live streaming tests between client and server. Publishes
			the camera and mic input to server, and plays it. Tests stream
			events, and enable/disable functionality.
			
		Client-Server Recorded Streaming
		
			Performs recorded stream ( non vp6 flv ) testing. Plays an
			individual stream from the server, and also plays a TV-stream
			set up on the server.
			
		Client-Server Stream Recording
		
			Tests stream recording capabilities of the server.
			
		Server-Server Connection
			
			Performs various connection tests between two servers.
			
		Server-Server Data Communication
		
			Tests invokes and AMF0 data exchange between two servers.
		
		Server-Server Live Streaming
		
			Publishes Camera and Microphone input to the host server, the
			server publishes the stream to the secondary server, then pulls
			it under a new name, and the client shows that stream.
			
		Server-Server Recorded Streaming
		
			Under construction.
			
		Multi-Stream Test
		
			Tests playing multiple streams from the server ( > 20 ). Tests
			rtmp channel overload, and rtmp channel page switching.
			
		FMS Compatibilty tests
		
			Connects Milenia to an FMS. There is also a sample fms application
			( main.asc ) under sources, with you can test fms to milenia 
			connection.
			
		Bandwidth check
		
			Tests download and upload bandwidth between client and server.
			These values will never be the maximum values of your connection,
			the maximum values are depending on the stepping time and buffer
			size of the server. For example, if io stepping is 20 millisecs and
			io ( socket ) buffer is 8192 bytes, then the maximum data troughput
			per second is ( 1000 / 20 ) * 8192 = 409600 bytes / s, or 400 K/s.
			
		Stress Test
		
			Stress test performs load test on the secondary server. It starts
			pushing a live stream to the server, and through multiple
			connections it pulls them from the server testing stream distribution
			and data throughput capabilities.
		

3. Programming the server


	3.1 Overview
		
		You can create custom applications or application packages for Milenia 
		Grafter Server in Java. You simply have to create a jar package from 
		your compiled classes / packages, and copy it under Milenia's custom 
		application	folder, and they are ready to use. 
		Custom applications are dynamically	loaded at startup or on the fly 
		triggered from the admin console. Custom applications must not be in 
		the classpath, otherwise jvm cannot	reload them.
		
		Development tip : always create a startup script, which compiles/packs 
		your custom application in your workspace, then copies it under milenia, 
		and starts up the server.
		
		To reach Milenia's API, you have to use the API classes packed in 
		Milenia. There are three main rules for a custom application:
		
		1. The main class of your application must be called Application
		2. The main class of your application must be in a package called 
		   application
		3. The main class of your application must implement IApplication 
		   interface
		
		You have to be careful on the server with threads, because various 
		events can come from various threads, use synchronization when there 
		can be concurrencies.
		
		There is also an important thing for the client side : never forget to 
		set AMF object encoding to AMF0 on the client side, because Milenia 
		uses AMF0.
		
		
	3.2 IApplication interface - com.milgra.server.api.IApplication
		
		You have to implement IApplication interface in the main class of your custom application. IApplication contains three main controller methods:
	
		onStart ( String nameX )
			
			Milenia triggers this function when an application is loaded. It
			receives the application's name with scope ( if it has one ).
			You can put initialization here, but its also good within the
			custom applications constructor.
		
		onClose ( )
			
			The server will call it when the admin unloads this application 
			from admin console during runtime. You have to define a complete 
			cleanup	code here to avoid memory leaks.
		
		onEnter ( Client clientX , WrapperList argumentsX )
		
			Client entering point, clientX is the client instance, messageX is 
			the wrapperlist containing the arguments passed by the client. 
			clientX will be in idle state, until you call the clientX.accept( ) 
			or clientX.reject( ) methods.
		
		onLeave ( Client clientX );
		
			Client leaving point, do client-related cleanup here.
			
	
	3.3 Client class - com.milgra.server.api.Client
	
		You can control connected ( passive ), and remote ( active ) client
		behaviour with this class.