[Asterisk-java-cvs] CVS: asterisk-java/xdocs tutorial.xml,NONE,1.1 navigation.xml,1.2,1.3 samples.xm
Brought to you by:
srt
Menu
▾
▴
[Asterisk-java-cvs] CVS: asterisk-java/xdocs tutorial.xml,NONE,1.1 navigation.xml,1.2,1.3 samples.xml,1.2,NONE
|
From: Stefan R. <sr...@us...> - 2005-03-11 23:17:58
|
Update of /cvsroot/asterisk-java/asterisk-java/xdocs In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv17522/xdocs Modified Files: navigation.xml Added Files: tutorial.xml Removed Files: samples.xml Log Message: Added tutorial covering basic FastAGI usage --- NEW FILE: tutorial.xml --- <?xml version="1.0"?> <!-- /* * Copyright 2004-2005 Stefan Reuter * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. * */ --> <document> <properties> <author email="srt at users.sourceforge.net">Stefan Reuter</author> <title>Samples</title> </properties> <meta name="keywords" content="Asterisk,asterisk,Java,java,Manager API,FastAGI,AGI,tutorial,example"/> <body> <section name="The FastAGI Protocol"> <p>The easiest way to interact with Asterisk from Java applications is via the FastAGI protocol.</p> <p>The AGI (Asterisk Gateway Interface) facility allows you to launch scripts, from the Asterisk dial plan. Traditionally communication between the scripts and Asterisk was via standard input and standard output and scripts had to run on the same machine as Asterisk. Due to the large amount of time a Java Virtual Machine needs for startup and the discomfort of having to install a Java environment on the PBX box(es) Java has not been the language of choice for writing AGI scripts.</p> <p>These drawbacks have been addressed by the addition of FastAGI to Asterisk. FastAGI is basically AGI over TCP/IP socket connections instead of using standard input and standard output as communication medium.</p> <p>Using FastAGI you can run a Java application (on the same machine that runs Asterisk or on a seperate machine) that is only started once and serves AGI scripts until it is shut down. Combined with Java's multithreading support you can build pretty fast AGI scripts using this protocol.</p> <p>Asterisk-java helps you with running your Java based AGI scripts by providing a container that recives connections from the Asterisk server, parses the request and calls your scripts mapped to the called URL.</p> <subsection name="Hello AGI!"> <p>To write your own AGI scripts you must implement the AGIScript interface. You can do so by simply extending AbstractAGIScript that provides some convenience methods that further simplify that task.</p> <p>A simple AGIScript might look as follows:</p> <source><![CDATA[ import net.sf.asterisk.fastagi.AGIChannel; import net.sf.asterisk.fastagi.AGIException; import net.sf.asterisk.fastagi.AGIRequest; import net.sf.asterisk.fastagi.AbstractAGIScript; public class HelloAGIScript extends AbstractAGIScript { public void service(AGIRequest request, AGIChannel channel) throws AGIException { // Answer the channel... answer(channel); // ...say hello... streamFile(channel, "welcome"); // ...and hangup. hangup(channel); } } ]]></source> <p>Put this Java source file into a directory of your choice, add the <code>asterisk-java.jar</code> and <code>commons-logging.jar</code> and compile it:</p> <source><![CDATA[ $ javac -cp asterisk-java.jar:commons-logging.jar HelloAGIScript.java $ ]]></source> <p>Next you have to add a call to your script to your dialplan in Asterisk.</p> <p>You might want to add an extension 1300 to the default section of your <code>extensions.conf</code>:</p> <source><![CDATA[ [default] ... exten => 1300,1,Agi(agi://localhost/hello.agi) ]]></source> <p>Replace localhost with the hostname of the machine that runs Asterisk-java.</p> <p>Be sure to reload Asterisk for this change to take effect. You can do so by executing <code>extensions reload</code> on the Asterisk CLI.</p> <p>Now you must map the script name <code>hello.agi</code> to the HelloAGIScript we just created. By default this is done in a properties file called <code>fastagi-mapping.properties</code> that must be on the classpath when we start the AGIServer. In this case it looks like:</p> <source><![CDATA[ hello.agi = HelloAGIScript ]]></source> <p>Your directory should now contain the following files:</p> <source><![CDATA[ $ ls -l -rw-r--r-- 1 srt srt 163689 2005-03-11 22:07 asterisk-java.jar -rw-r--r-- 1 srt srt 26388 2005-03-11 22:06 commons-logging.jar -rw-r--r-- 1 srt srt 26 2005-03-11 20:50 fastagi-mapping.properties -rw-r--r-- 1 srt srt 624 2005-03-11 22:07 HelloAGIScript.class -rw-r--r-- 1 srt srt 438 2005-03-11 20:50 HelloAGIScript.java ]]></source> <p>Finally we start the AGIServer:</p> <source><![CDATA[ $ java -cp commons-logging.jar:asterisk-java.jar:. net.sf.asterisk.fastagi.DefaultAGIServer ]]></source> <p>You should see some logging output indicating that the AGIServer has been successfully started and is listening for incoming connections:</p> <source><![CDATA[ Mar 11, 2005 10:20:12 PM net.sf.asterisk.fastagi.DefaultAGIServer run INFO: Thread pool started. Mar 11, 2005 10:20:12 PM net.sf.asterisk.fastagi.DefaultAGIServer run INFO: Listening on *:4573. ]]></source> <p>When you call extension 1300 you will see the AGI script being launched:</p> <source><![CDATA[ Mar 11, 2005 10:22:47 PM net.sf.asterisk.fastagi.DefaultAGIServer run INFO: Received connection. Mar 11, 2005 10:22:47 PM net.sf.asterisk.fastagi.AGIConnectionHandler run INFO: Begin AGIScript HelloAGIScript on AGIServer-TaskThread-0 Mar 11, 2005 10:22:48 PM net.sf.asterisk.fastagi.AGIConnectionHandler run INFO: End AGIScript HelloAGIScript on AGIServer-TaskThread-0 ]]></source> </subsection> <subsection name="Configuration"> <p>You can tune the DefaultAGIServer by setting two properties: The bindPort and the poolSize.</p> <p>The bindPort determines the TCP port the server will listen on. By default this is the FastAGI port 4573. If you change it make sure to include the new port in your URLs used in <code>extensions.conf</code>. When using bindPort 1234 your <code>extensions.conf</code> will look like:</p> <source><![CDATA[ exten => 1300,1,Agi(agi://localhost:1234/hello.agi) ]]></source> <p>To understand the poolSize property you need to know that the DefaultAGIServer uses a fixed size thread pool to serve your AGIScripts. The poolSize determines how many threads are spawned at startup and thus limits the number of AGIScripts that can run at the same time. So you should set the poolSize to at least the number of concurrent calls your AGIServer should be able to handle. The default value is 10.</p> <p>These configuration properties can be set by providing a <code>fastagi.properties</code> file on the classpath.</p> <p>This might look like:</p> <source><![CDATA[ bindPort = 1234 poolSize = 20 ]]></source> </subsection> </section> </body> </document> Index: navigation.xml =================================================================== RCS file: /cvsroot/asterisk-java/asterisk-java/xdocs/navigation.xml,v retrieving revision 1.2 retrieving revision 1.3 diff -u -d -p -r1.2 -r1.3 --- navigation.xml 24 Feb 2005 23:05:18 -0000 1.2 +++ navigation.xml 11 Mar 2005 23:17:46 -0000 1.3 @@ -29,7 +29,7 @@ <item name="Mailing Lists" href="mail-lists.html"/> </menu> <menu name="Documentation"> - <item name="Samples" href="samples.html"/> + <item name="Tutorial" href="tutorial.html"/> </menu> <search/> <menu type="footer"> --- samples.xml DELETED --- |
