You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@etch.apache.org by ve...@apache.org on 2011/12/15 15:35:39 UTC
svn commit: r1214782 [2/5] - in /incubator/etch/site/trunk/content/etch: ./
documentation/ documentation/architecture.data/
documentation/howto-logger-filter.data/ documentation/resources/
Added: incubator/etch/site/trunk/content/etch/documentation/example-hello-world.html
URL: http://svn.apache.org/viewvc/incubator/etch/site/trunk/content/etch/documentation/example-hello-world.html?rev=1214782&view=auto
==============================================================================
--- incubator/etch/site/trunk/content/etch/documentation/example-hello-world.html (added)
+++ incubator/etch/site/trunk/content/etch/documentation/example-hello-world.html Thu Dec 15 14:35:38 2011
@@ -0,0 +1,181 @@
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<HTML>
+ <HEAD>
+ <LINK type="text/css" rel="stylesheet" href="resources/space.css">
+ <STYLE type="text/css">
+ .footer {
+ background-image: url('https://cwiki.apache.org/confluence/images/border/border_bottom.gif');
+ background-repeat: repeat-x;
+ background-position: left top;
+ padding-top: 4px;
+ color: #666;
+ }
+ </STYLE>
+ <SCRIPT type="text/javascript" language="javascript">
+ var hide = null;
+ var show = null;
+ var children = null;
+
+ function init() {
+ /* Search form initialization */
+ var form = document.forms['search'];
+ if (form != null) {
+ form.elements['domains'].value = location.hostname;
+ form.elements['sitesearch'].value = location.hostname;
+ }
+
+ /* Children initialization */
+ hide = document.getElementById('hide');
+ show = document.getElementById('show');
+ children = document.all != null ?
+ document.all['children'] :
+ document.getElementById('children');
+ if (children != null) {
+ children.style.display = 'none';
+ show.style.display = 'inline';
+ hide.style.display = 'none';
+ }
+ }
+
+ function showChildren() {
+ children.style.display = 'block';
+ show.style.display = 'none';
+ hide.style.display = 'inline';
+ }
+
+ function hideChildren() {
+ children.style.display = 'none';
+ show.style.display = 'inline';
+ hide.style.display = 'none';
+ }
+ </SCRIPT>
+ <TITLE>Example - Hello World</TITLE>
+ <META http-equiv="Content-Type" content="text/html;charset=UTF-8"></HEAD>
+ <BODY onload="init()">
+ <DIV id="PageContent">
+ <DIV class="pagecontent">
+ <DIV class="wiki-content">
+ <TABLE>
+ <TR>
+ <TD>
+ <H2><A name="Example-HelloWorld-HelloEtch"></A>Hello Etch</H2>
+
+<P>The classic helloworld example in Etch is provided in examples/helloworld (both svn and releases, starting with 1.1). </P>
+
+<P>You will find the following directory structure:</P>
+
+<UL>
+ <LI>build.xml</LI>
+ <LI>README.txt</LI>
+ <LI>src
+ <UL>
+ <LI>main
+ <UL>
+ <LI>csharp (csharp implementation)</LI>
+ <LI>java (java implementation)</LI>
+ <LI>c (c implementation)</LI>
+ <LI>etch
+ <UL>
+ <LI>HelloWorld.etch (NSDL service description)</LI>
+ </UL>
+ </LI>
+ </UL>
+ </LI>
+ <LI>target (created on build, contains generated parts)</LI>
+ </UL>
+ </LI>
+</UL>
+
+
+
+<P>You can build the HelloWorld example (generate source from HelloWorld.etch, compile and test) for Java and CSharp on the command line using</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+cd examples/helloworld
+ant Debug
+</PRE>
+</DIV></DIV>
+
+<P>Note that you must setup your command line environment correctly. If you have checked out the trunk from svn, use scripts/antSetup.bat and the information in <A href="building-trunk.html" title="Building Trunk">Building Trunk</A>.</P>
+
+<H2><A name="Example-HelloWorld-HelloWorldNSDL"></A>HelloWorld NSDL</H2>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+module org.apache.etch.examples.helloworld
+
+service HelloWorld {
+ struct user (
+ <SPAN class="code-object">int</SPAN> id,
+ string name
+ )
+
+ exception UserUnknownException (
+ string mes
+ )
+
+ @Direction(Server)
+ string say_hello(user to_whom) <SPAN class="code-keyword">throws</SPAN> UserUnknownException
+
+}
+</PRE>
+</DIV></DIV>
+
+<P>The service provides the say_hello method, which should greet a user, which is supplied as a parameter.</P>
+
+<H2><A name="Example-HelloWorld-JavaHelloWorldinmoredetail"></A>Java HelloWorld in more detail</H2>
+
+<P>The implementation of the example server and client is located in:</P>
+
+<P>trunk\examples\helloworld\src\main\java\org\apache\etch\examples\helloworld\</P>
+
+<P>The classes MainHelloWorldListener and MainHelloWorldClient spawn the server and client parts of the helloworld example. </P>
+
+<P>The Client code is:</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+<SPAN class="code-object">String</SPAN> uri = <SPAN class="code-quote">"tcp:<SPAN class="code-comment">//127.0.0.1:4001"</SPAN>;
+</SPAN>RemoteHelloWorldServer server = HelloWorldHelper.newServer( uri, <SPAN class="code-keyword">null</SPAN>,<SPAN class="code-keyword">new</SPAN> MainHelloWorldClient() );
+server._startAndWaitUp( 4000 );
+user u = <SPAN class="code-keyword">new</SPAN> user(5, <SPAN class="code-quote">"Testuser"</SPAN>);
+<SPAN class="code-object">System</SPAN>.out.println(server.say_hello(u));
+server._stopAndWaitDown( 4000 );
+</PRE>
+</DIV></DIV>
+
+<P>It connects to an Etch server running on localhost by constructing a new RemoteHelloWorldServer object (the proxy in the rpc sense) using the HelloWorldHelper class, which is generated from the NSDL. Afterwards the connection is started and the say_hello method is called. </P>
+
+<P>Starting a server is also quite simple:</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+<SPAN class="code-object">String</SPAN> uri = <SPAN class="code-quote">"tcp:<SPAN class="code-comment">//127.0.0.1:4001"</SPAN>;
+</SPAN>ServerFactory listener = HelloWorldHelper.newListener( uri, <SPAN class="code-keyword">null</SPAN>, <SPAN class="code-keyword">new</SPAN> MainHelloWorldListener() );
+listener.transportControl( Transport.START_AND_WAIT_UP, 4000 );
+</PRE>
+</DIV></DIV>
+
+<P>The last parameter of newListener must implement the HelloWorldServerFactory interface, which defines the newHelloWorldServer factory method. This method is called by the etch runtime once for every client connect and must return an instance of ImplHelloWorldServer, which is the implementation class for the services that are invoked for that specific connected client. In the code for the client above you can see the same principle for the client. This already shows Etch's basic principle of two-way communication: The Client has an Impl... object, too. It contains all @Direction(client) methods from the IDL (in this small example, there are none. see the chat example for client-side methods.)</P>
+
+
+ </DIV>
+
+
+
+ </DIV>
+ </DIV>
+ <!--
+ <div class="footer">
+ Generated by
+ <a href="http://www.atlassian.com/confluence/">Atlassian Confluence</a> (Version: 3.2 Build: 1810 Mar 16, 2010)
+ <a href="http://could.it/autoexport/">Auto Export Plugin</a> (Version: 1.0.0- dkulp)
+ </div>
+ -->
+</TD>
+</TR>
+</TABLE>
+ </BODY>
+</HTML>
Added: incubator/etch/site/trunk/content/etch/documentation/examples.html
URL: http://svn.apache.org/viewvc/incubator/etch/site/trunk/content/etch/documentation/examples.html?rev=1214782&view=auto
==============================================================================
--- incubator/etch/site/trunk/content/etch/documentation/examples.html (added)
+++ incubator/etch/site/trunk/content/etch/documentation/examples.html Thu Dec 15 14:35:38 2011
@@ -0,0 +1,83 @@
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<HTML>
+ <HEAD>
+ <LINK type="text/css" rel="stylesheet" href="resources/space.css">
+ <STYLE type="text/css">
+ .footer {
+ background-image: url('https://cwiki.apache.org/confluence/images/border/border_bottom.gif');
+ background-repeat: repeat-x;
+ background-position: left top;
+ padding-top: 4px;
+ color: #666;
+ }
+ </STYLE>
+ <SCRIPT type="text/javascript" language="javascript">
+ var hide = null;
+ var show = null;
+ var children = null;
+
+ function init() {
+ /* Search form initialization */
+ var form = document.forms['search'];
+ if (form != null) {
+ form.elements['domains'].value = location.hostname;
+ form.elements['sitesearch'].value = location.hostname;
+ }
+
+ /* Children initialization */
+ hide = document.getElementById('hide');
+ show = document.getElementById('show');
+ children = document.all != null ?
+ document.all['children'] :
+ document.getElementById('children');
+ if (children != null) {
+ children.style.display = 'none';
+ show.style.display = 'inline';
+ hide.style.display = 'none';
+ }
+ }
+
+ function showChildren() {
+ children.style.display = 'block';
+ show.style.display = 'none';
+ hide.style.display = 'inline';
+ }
+
+ function hideChildren() {
+ children.style.display = 'none';
+ show.style.display = 'inline';
+ hide.style.display = 'none';
+ }
+ </SCRIPT>
+ <TITLE>Examples</TITLE>
+ <META http-equiv="Content-Type" content="text/html;charset=UTF-8"></HEAD>
+ <BODY onload="init()">
+ <DIV id="PageContent">
+ <DIV class="pagecontent">
+ <DIV class="wiki-content">
+<TABLE>
+<TR>
+<TD class="" valign="top" width="90%">
+<P><H2><A name="Examples-ApplicationExamples"></A>Application Examples</H2>
+
+<UL>
+ <LI><A href="example-hello-world.html" title="Example - Hello World">Hello World</A></LI>
+ <LI><A href="http://developer.cisco.com/web/cuae/devconf2008_session_3" class="external-link" rel="nofollow">2008 Developer Conference Video</A> - video from the 2008 Cisco Unified Application Environment Developer's conference where Etch was introduced.</LI>
+</UL>
+</P></TD></TR></TBODY></TABLE>
+ </DIV>
+
+
+
+ </DIV>
+ </DIV>
+ <!--
+ <div class="footer">
+ Generated by
+ <a href="http://www.atlassian.com/confluence/">Atlassian Confluence</a> (Version: 3.2 Build: 1810 Mar 16, 2010)
+ <a href="http://could.it/autoexport/">Auto Export Plugin</a> (Version: 1.0.0- dkulp)
+ </div>
+ -->
+ </BODY>
+</HTML>
Added: incubator/etch/site/trunk/content/etch/documentation/generated-code-users-guide.html
URL: http://svn.apache.org/viewvc/incubator/etch/site/trunk/content/etch/documentation/generated-code-users-guide.html?rev=1214782&view=auto
==============================================================================
--- incubator/etch/site/trunk/content/etch/documentation/generated-code-users-guide.html (added)
+++ incubator/etch/site/trunk/content/etch/documentation/generated-code-users-guide.html Thu Dec 15 14:35:38 2011
@@ -0,0 +1,104 @@
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<HTML>
+ <HEAD>
+ <LINK type="text/css" rel="stylesheet" href="resources/space.css">
+ <STYLE type="text/css">
+ .footer {
+ background-image: url('https://cwiki.apache.org/confluence/images/border/border_bottom.gif');
+ background-repeat: repeat-x;
+ background-position: left top;
+ padding-top: 4px;
+ color: #666;
+ }
+ </STYLE>
+ <SCRIPT type="text/javascript" language="javascript">
+ var hide = null;
+ var show = null;
+ var children = null;
+
+ function init() {
+ /* Search form initialization */
+ var form = document.forms['search'];
+ if (form != null) {
+ form.elements['domains'].value = location.hostname;
+ form.elements['sitesearch'].value = location.hostname;
+ }
+
+ /* Children initialization */
+ hide = document.getElementById('hide');
+ show = document.getElementById('show');
+ children = document.all != null ?
+ document.all['children'] :
+ document.getElementById('children');
+ if (children != null) {
+ children.style.display = 'none';
+ show.style.display = 'inline';
+ hide.style.display = 'none';
+ }
+ }
+
+ function showChildren() {
+ children.style.display = 'block';
+ show.style.display = 'none';
+ hide.style.display = 'inline';
+ }
+
+ function hideChildren() {
+ children.style.display = 'none';
+ show.style.display = 'inline';
+ hide.style.display = 'none';
+ }
+ </SCRIPT>
+ <TITLE>Generated Code Users Guide</TITLE>
+ <META http-equiv="Content-Type" content="text/html;charset=UTF-8"></HEAD>
+ <BODY onload="init()">
+ <DIV id="PageContent">
+ <DIV class="pagecontent">
+ <DIV class="wiki-content">
+
+<TABLE>
+<TR>
+<TD class="" valign="top" width="90%">
+<P><H2><A name="GeneratedCodeUsersGuide-CSharpBindingUserGuide"></A>C Sharp Binding User Guide</H2>
+
+<P>Best documentation for generated code is available for the C# Binding:</P>
+
+<UL>
+ <LI><A href="csharp-binding-users-guide.html" title="Csharp Binding Users Guide">Csharp Binding Users Guide</A></LI>
+</UL>
+
+
+<H2><A name="GeneratedCodeUsersGuide-JavaUserGuide"></A>Java User Guide</H2>
+
+<P>The generated Java Binding code follows the same structure as the C# binding. We will provide more detailed documentation on those bindings in the future. Reading the Csharp Compiler User Guide should also help with understanding the generated java code.</P>
+
+<H2><A name="GeneratedCodeUsersGuide-CBindingUserGuide"></A>C Binding User Guide</H2>
+
+<UL>
+ <LI><A href="c-binding-tips-tricks.html" title="C Binding Tips & Tricks">C Binding Tips & Tricks</A></LI>
+</UL>
+
+
+
+<H2><A name="GeneratedCodeUsersGuide-JavaScriptBinding%28indevelopment%29"></A>JavaScript Binding (in development)</H2>
+
+<UL>
+ <LI><A href="javascript-language-binding.html" title="Javascript Language Binding">Javascript Language Binding</A></LI>
+</UL>
+</P></TD></TR></TBODY></TABLE><TD></TD>
+ </DIV>
+
+
+
+ </DIV>
+ </DIV>
+ <!--
+ <div class="footer">
+ Generated by
+ <a href="http://www.atlassian.com/confluence/">Atlassian Confluence</a> (Version: 3.4.6 Build: 2036 Dec 21, 2010)
+ <a href="http://could.it/autoexport/">Auto Export Plugin</a> (Version: 1.0.0- dkulp)
+ </div>
+ -->
+ </BODY>
+</HTML>
Added: incubator/etch/site/trunk/content/etch/documentation/howto-keepalive-filter.html
URL: http://svn.apache.org/viewvc/incubator/etch/site/trunk/content/etch/documentation/howto-keepalive-filter.html?rev=1214782&view=auto
==============================================================================
--- incubator/etch/site/trunk/content/etch/documentation/howto-keepalive-filter.html (added)
+++ incubator/etch/site/trunk/content/etch/documentation/howto-keepalive-filter.html Thu Dec 15 14:35:38 2011
@@ -0,0 +1,150 @@
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<HTML>
+ <HEAD>
+ <LINK type="text/css" rel="stylesheet" href="resources/space.css">
+ <STYLE type="text/css">
+ .footer {
+ background-image: url('https://cwiki.apache.org/confluence/images/border/border_bottom.gif');
+ background-repeat: repeat-x;
+ background-position: left top;
+ padding-top: 4px;
+ color: #666;
+ }
+ </STYLE>
+ <SCRIPT type="text/javascript" language="javascript">
+ var hide = null;
+ var show = null;
+ var children = null;
+
+ function init() {
+ /* Search form initialization */
+ var form = document.forms['search'];
+ if (form != null) {
+ form.elements['domains'].value = location.hostname;
+ form.elements['sitesearch'].value = location.hostname;
+ }
+
+ /* Children initialization */
+ hide = document.getElementById('hide');
+ show = document.getElementById('show');
+ children = document.all != null ?
+ document.all['children'] :
+ document.getElementById('children');
+ if (children != null) {
+ children.style.display = 'none';
+ show.style.display = 'inline';
+ hide.style.display = 'none';
+ }
+ }
+
+ function showChildren() {
+ children.style.display = 'block';
+ show.style.display = 'none';
+ hide.style.display = 'inline';
+ }
+
+ function hideChildren() {
+ children.style.display = 'none';
+ show.style.display = 'inline';
+ hide.style.display = 'none';
+ }
+ </SCRIPT>
+ <TITLE>Howto - KeepAlive Filter</TITLE>
+ <META http-equiv="Content-Type" content="text/html;charset=UTF-8"></HEAD>
+ <BODY onload="init()">
+ <DIV id="PageContent">
+ <DIV class="pagecontent">
+ <DIV class="wiki-content">
+
+
+<TABLE>
+<TR>
+<TD class="" valign="top" width="90%">
+<P><DIV class="navmenu" style="float:right; background:white; margin:3px; padding:3px"><STYLE type="text/css">/*<![CDATA[*/
+div.rbtoc1249351883863 {margin-left: 0px;padding: 0px;}
+div.rbtoc1249351883863 ul {list-style: none;margin-left: 0px;}
+div.rbtoc1249351883863 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</STYLE><DIV class="rbtoc1249351883863">
+<UL>
+ <LI><SPAN class="TOCOutline">1</SPAN> <A href="#Howto-KeepAliveFilter-KeepAliveFilter">KeepAlive Filter</A></LI>
+<UL>
+ <LI><SPAN class="TOCOutline">1.1</SPAN> <A href="#Howto-KeepAliveFilter-KeepAliveOperation">KeepAlive Operation</A></LI>
+ <LI><SPAN class="TOCOutline">1.2</SPAN> <A href="#Howto-KeepAliveFilter-KeepAliveParameters">KeepAlive Parameters</A></LI>
+ <LI><SPAN class="TOCOutline">1.3</SPAN> <A href="#Howto-KeepAliveFilter-KeepAliveSessionNotify">KeepAlive SessionNotify</A></LI>
+ <LI><SPAN class="TOCOutline">1.4</SPAN> <A href="#Howto-KeepAliveFilter-KeepAliveExamples">KeepAlive Examples</A></LI>
+ <LI><SPAN class="TOCOutline">1.5</SPAN> <A href="#Howto-KeepAliveFilter-KeepAliveIssues">KeepAlive Issues</A></LI>
+</UL>
+</UL></DIV></DIV>
+
+<H1><A name="Howto-KeepAliveFilter-KeepAliveFilter"></A>KeepAlive Filter</H1>
+
+<P>The etch KeepAlive filter is a message filter which periodically checks the health of a connection and resets it if it not responsive. The filter must be added to both sides of the connection to be effective.</P>
+
+<H2><A name="Howto-KeepAliveFilter-KeepAliveOperation"></A>KeepAlive Operation</H2>
+
+<P>The client periodically sends a request message to the server. The server responds by sending a response message to the client.</P>
+
+<P>Both client and server periodically check to see how long it has been since the last KeepAlive message was received from the other side. If the time since the last KeepAlive message was received is too great, the connection is reset.</P>
+
+<H2><A name="Howto-KeepAliveFilter-KeepAliveParameters"></A>KeepAlive Parameters</H2>
+
+<P>There are two parameters which control KeepAlive:</P>
+<UL>
+ <LI>KeepAlive.delay - the number of seconds between sends (client) and checks (client and server). Value is number of seconds. The default value is 15 seconds.</LI>
+ <LI>KeepAlive.count - the number of delay intervals without a message before the connection is reset. Value is number of delay intervals. The default value is 4.</LI>
+</UL>
+
+
+<P>The server adopts the settings (per connection) of the client.</P>
+
+<H2><A name="Howto-KeepAliveFilter-KeepAliveSessionNotify"></A>KeepAlive SessionNotify</H2>
+
+<P>When KeepAlive decides to reset a connection, it also notifies the session with an event:</P>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>"KeepAlive resetting dead connection"
+</PRE>
+</DIV></DIV>
+
+<H2><A name="Howto-KeepAliveFilter-KeepAliveExamples"></A>KeepAlive Examples</H2>
+
+<P>Start KeepAlive with default parameters.</P>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>tcp://localhost:4001?filter=KeepAlive
+</PRE>
+</DIV></DIV>
+
+<P>Start KeepAlive with a delay of 60 seconds and a count of 5.</P>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>tcp://localhost:4001?filter=KeepAlive&KeepAlive.delay=60&KeepAlive.count=5
+</PRE>
+</DIV></DIV>
+
+<H2><A name="Howto-KeepAliveFilter-KeepAliveIssues"></A>KeepAlive Issues</H2>
+
+<P>A few issues with KeepAlive come to mind:</P>
+<UL>
+ <LI>Client specified parameters override server. Seemed like a good idea at the time. On reflection I think the server settings ought to rule. Centralized management, etc.</LI>
+ <LI>If a really long running operation is holding up the message receiver thread then the connection will be declared dead and reset. Not necessarily a bad thing, just something to note.</LI>
+ <LI>Server is passive and only sends a message to client when it receives a message from client. Again, not exactly an issue, just something to note.</LI>
+</UL>
+</P></TD></TR></TBODY></TABLE>
+ </DIV>
+
+
+
+ </DIV>
+ </DIV>
+ <!--
+ <div class="footer">
+ Generated by
+ <a href="http://www.atlassian.com/confluence/">Atlassian Confluence</a> (Version: 3.2 Build: 1810 Mar 16, 2010)
+ <a href="http://could.it/autoexport/">Auto Export Plugin</a> (Version: 1.0.0- dkulp)
+ </div>
+ -->
+ </BODY>
+</HTML>
Added: incubator/etch/site/trunk/content/etch/documentation/howto-logger-filter.data/FileRename.JPG
URL: http://svn.apache.org/viewvc/incubator/etch/site/trunk/content/etch/documentation/howto-logger-filter.data/FileRename.JPG?rev=1214782&view=auto
==============================================================================
Files incubator/etch/site/trunk/content/etch/documentation/howto-logger-filter.data/FileRename.JPG (added) and incubator/etch/site/trunk/content/etch/documentation/howto-logger-filter.data/FileRename.JPG Thu Dec 15 14:35:38 2011 differ
Added: incubator/etch/site/trunk/content/etch/documentation/howto-logger-filter.data/FileRename.JPG.jpeg
URL: http://svn.apache.org/viewvc/incubator/etch/site/trunk/content/etch/documentation/howto-logger-filter.data/FileRename.JPG.jpeg?rev=1214782&view=auto
==============================================================================
Files incubator/etch/site/trunk/content/etch/documentation/howto-logger-filter.data/FileRename.JPG.jpeg (added) and incubator/etch/site/trunk/content/etch/documentation/howto-logger-filter.data/FileRename.JPG.jpeg Thu Dec 15 14:35:38 2011 differ
Added: incubator/etch/site/trunk/content/etch/documentation/howto-logger-filter.html
URL: http://svn.apache.org/viewvc/incubator/etch/site/trunk/content/etch/documentation/howto-logger-filter.html?rev=1214782&view=auto
==============================================================================
--- incubator/etch/site/trunk/content/etch/documentation/howto-logger-filter.html (added)
+++ incubator/etch/site/trunk/content/etch/documentation/howto-logger-filter.html Thu Dec 15 14:35:38 2011
@@ -0,0 +1,162 @@
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<HTML>
+ <HEAD>
+ <LINK type="text/css" rel="stylesheet" href="resources/space.css">
+ <STYLE type="text/css">
+ .footer {
+ background-image: url('https://cwiki.apache.org/confluence/images/border/border_bottom.gif');
+ background-repeat: repeat-x;
+ background-position: left top;
+ padding-top: 4px;
+ color: #666;
+ }
+ </STYLE>
+ <SCRIPT type="text/javascript" language="javascript">
+ var hide = null;
+ var show = null;
+ var children = null;
+
+ function init() {
+ /* Search form initialization */
+ var form = document.forms['search'];
+ if (form != null) {
+ form.elements['domains'].value = location.hostname;
+ form.elements['sitesearch'].value = location.hostname;
+ }
+
+ /* Children initialization */
+ hide = document.getElementById('hide');
+ show = document.getElementById('show');
+ children = document.all != null ?
+ document.all['children'] :
+ document.getElementById('children');
+ if (children != null) {
+ children.style.display = 'none';
+ show.style.display = 'inline';
+ hide.style.display = 'none';
+ }
+ }
+
+ function showChildren() {
+ children.style.display = 'block';
+ show.style.display = 'none';
+ hide.style.display = 'inline';
+ }
+
+ function hideChildren() {
+ children.style.display = 'none';
+ show.style.display = 'inline';
+ hide.style.display = 'none';
+ }
+ </SCRIPT>
+ <TITLE>Howto - Logger Filter</TITLE>
+ <META http-equiv="Content-Type" content="text/html;charset=UTF-8"></HEAD>
+ <BODY onload="init()">
+ <DIV id="PageContent">
+ <DIV class="pagecontent">
+ <DIV class="wiki-content">
+<TABLE>
+<TR>
+<TD class="" valign="top" width="90%">
+
+<H1><A name="Howto-LoggerFilter-LoggerFilter"></A>Logger Filter</H1>
+
+<P>The purpose of this document is to provide an overview on how to setup Logger Filter in Etch. As the name suggests, Logger filter logs etch messages and events into a file.<BR>
+Logger Filter can be enabled for Client, Listener or both. </P>
+
+<H2><A name="Howto-LoggerFilter-LoggerFilterParameters"></A>Logger Filter Parameters</H2>
+
+<P>Logger.filePath - This parameter is used to define the location and name of the logFile. For example Logger.filePath=C:\test\log\server.txt, in this case etch messages and<BR>
+events will be logged to file C:\test\log\server.txt. If a user then does define this parameter, then etch will use a default file for logging (Log.txt)</P>
+
+<H2><A name="Howto-LoggerFilter-HowtoenableLoggerFilter"></A>How to enable Logger Filter</H2>
+
+<P>Change uri to one of the following</P>
+
+<UL>
+ <LI>string uri ="tcp://localhost:4006?filter=Logger&Logger.filePath=C:\test\log\server.txt";</LI>
+</UL>
+
+
+<P> Logs will be written to C:\test\log\server.txt</P>
+
+<UL>
+ <LI>string uri = "tcp://localhost:4006?filter=Logger</LI>
+</UL>
+
+
+<P> In this case, logs will be written to default file Log.txt</P>
+
+
+<H2><A name="Howto-LoggerFilter-SnippetofLogFile"></A>Snippet of Log File</H2>
+
+<DIV class="preformatted panel" style="border-width: 1px; width: 800px;"><DIV class="preformattedContent panelContent">
+<PRE>16:11:49.593: Incoming: Messagizer : Packetizer / TcpConnection(up, 127.0.0.1:4006, 127.0.0.1:3161)
+16:11:49.609: Incoming: etch.examples.example.Example.hello(-1567573670): {msg(769750364)=I am printing message 0, _messageId(1661383784)=633512167095000000}
+16:11:49.609: Outgoing: etch.examples.example.Example._result_hello(92919767): {_inReplyTo(-307705434)=633512167095000000, result(-2130379326)=0}
+16:11:49.625: Incoming: etch.examples.example.Example.hello(-1567573670): {msg(769750364)=I am printing message 1, _messageId(1661383784)=633512167095000037}
+16:11:49.625: Outgoing: etch.examples.example.Example._result_hello(92919767): {_inReplyTo(-307705434)=633512167095000037, result(-2130379326)=0}
+16:11:49.625: Incoming: etch.examples.example.Example.hello(-1567573670): {msg(769750364)=I am printing message 2, _messageId(1661383784)=633512167095000074}
+16:11:49.625: Outgoing: etch.examples.example.Example._result_hello(92919767): {_inReplyTo(-307705434)=633512167095000074, result(-2130379326)=0}
+16:11:49.625: Incoming: etch.examples.example.Example.hello(-1567573670): {msg(769750364)=I am printing message 3, _messageId(1661383784)=633512167095000111}
+16:11:49.625: Outgoing: etch.examples.example.Example._result_hello(92919767): {_inReplyTo(-307705434)=633512167095000111, result(-2130379326)=0}
+16:11:49.625: Incoming: etch.examples.example.Example.hello(-1567573670): {msg(769750364)=I am printing message 4, _messageId(1661383784)=633512167095000148}
+16:11:49.625: Outgoing: etch.examples.example.Example._result_hello(92919767): {_inReplyTo(-307705434)=633512167095000148, result(-2130379326)=0}
+16:11:49.625: Incoming: etch.examples.example.Example.hello(-1567573670): {msg(769750364)=I am printing message 5, _messageId(1661383784)=633512167095000185}
+16:11:49.625: Outgoing: etch.examples.example.Example._result_hello(92919767): {_inReplyTo(-307705434)=633512167095000185, result(-2130379326)=0}
+16:11:49.625: Incoming: etch.examples.example.Example.hello(-1567573670): {msg(769750364)=I am printing message 6, _messageId(1661383784)=633512167095000222}
+16:11:49.625: Outgoing: etch.examples.example.Example._result_hello(92919767): {_inReplyTo(-307705434)=633512167095000222, result(-2130379326)=0}
+16:11:49.625: Incoming: etch.examples.example.Example.hello(-1567573670): {msg(769750364)=I am printing message 7, _messageId(1661383784)=633512167095000259}
+16:11:49.625: Outgoing: etch.examples.example.Example._result_hello(92919767): {_inReplyTo(-307705434)=633512167095000259, result(-2130379326)=0}
+</PRE>
+</DIV></DIV>
+
+
+<H2><A name="Howto-LoggerFilter-Issues"></A>Issues</H2>
+
+<UL>
+ <LI><B>How to prevent overwriting of log file ?</B></LI>
+</UL>
+
+
+<P> The current solution is to rename the older log file. The name of the file will be based on the current time. Image below depicts the name format of the older log files</P>
+
+<DIV class="" align="center"><SPAN class="image-wrap" style=""><IMG src="howto-logger-filter.data/FileRename.JPG" style="border: 0px solid black"></SPAN></DIV>
+
+
+<UL>
+ <LI><B>When to flush the contents of the buffer to file ?</B></LI>
+</UL>
+
+
+<P> Option 1 is to flush the contents immediately (may lead to a performance hit)<BR>
+ Option 2 is to do it periodically (user will be given the flexibility to chose the time interval for e.g. user can specify flush buffer every 2 minutes)<BR>
+ Option 3 is not to flush the buffer at all</P>
+
+<P> Currently only Option 1 has been implemented. </P>
+
+<UL>
+ <LI><B>Should we set a limit on the file size ? In other words, how large should we allow a log file to get before we create a new log file ?</B></LI>
+</UL>
+
+
+<UL>
+ <LI><B>At some point, should very old log files be deleted ?</B></LI>
+</UL>
+</P></TD></TR></TBODY></TABLE>
+ </DIV>
+
+
+
+ </DIV>
+ </DIV>
+ <!--
+ <div class="footer">
+ Generated by
+ <a href="http://www.atlassian.com/confluence/">Atlassian Confluence</a> (Version: 3.2 Build: 1810 Mar 16, 2010)
+ <a href="http://could.it/autoexport/">Auto Export Plugin</a> (Version: 1.0.0- dkulp)
+ </div>
+ -->
+ </BODY>
+</HTML>
Added: incubator/etch/site/trunk/content/etch/documentation/howto-pwauth-filter.html
URL: http://svn.apache.org/viewvc/incubator/etch/site/trunk/content/etch/documentation/howto-pwauth-filter.html?rev=1214782&view=auto
==============================================================================
--- incubator/etch/site/trunk/content/etch/documentation/howto-pwauth-filter.html (added)
+++ incubator/etch/site/trunk/content/etch/documentation/howto-pwauth-filter.html Thu Dec 15 14:35:38 2011
@@ -0,0 +1,156 @@
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<HTML>
+ <HEAD>
+ <LINK type="text/css" rel="stylesheet" href="resources/space.css">
+ <STYLE type="text/css">
+ .footer {
+ background-image: url('https://cwiki.apache.org/confluence/images/border/border_bottom.gif');
+ background-repeat: repeat-x;
+ background-position: left top;
+ padding-top: 4px;
+ color: #666;
+ }
+ </STYLE>
+ <SCRIPT type="text/javascript" language="javascript">
+ var hide = null;
+ var show = null;
+ var children = null;
+
+ function init() {
+ /* Search form initialization */
+ var form = document.forms['search'];
+ if (form != null) {
+ form.elements['domains'].value = location.hostname;
+ form.elements['sitesearch'].value = location.hostname;
+ }
+
+ /* Children initialization */
+ hide = document.getElementById('hide');
+ show = document.getElementById('show');
+ children = document.all != null ?
+ document.all['children'] :
+ document.getElementById('children');
+ if (children != null) {
+ children.style.display = 'none';
+ show.style.display = 'inline';
+ hide.style.display = 'none';
+ }
+ }
+
+ function showChildren() {
+ children.style.display = 'block';
+ show.style.display = 'none';
+ hide.style.display = 'inline';
+ }
+
+ function hideChildren() {
+ children.style.display = 'none';
+ show.style.display = 'inline';
+ hide.style.display = 'none';
+ }
+ </SCRIPT>
+ <TITLE>Howto - Pwauth Filter</TITLE>
+ <META http-equiv="Content-Type" content="text/html;charset=UTF-8"></HEAD>
+ <BODY onload="init()">
+ <DIV id="PageContent">
+ <DIV class="pagecontent">
+ <DIV class="wiki-content">
+<TABLE>
+<TR>
+<TD class="" valign="top" width="90%">
+<P><DIV class="navmenu" style="float:right; background:white; margin:3px; padding:3px"><STYLE type="text/css">/*<![CDATA[*/
+div.rbtoc1249351885032 {margin-left: 0px;padding: 0px;}
+div.rbtoc1249351885032 ul {list-style: none;margin-left: 0px;}
+div.rbtoc1249351885032 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</STYLE><DIV class="rbtoc1249351885032">
+<UL>
+ <LI><SPAN class="TOCOutline">1</SPAN> <A href="#Howto-PwauthFilter-PwAuthFilter">PwAuth Filter</A></LI>
+<UL>
+ <LI><SPAN class="TOCOutline">1.1</SPAN> <A href="#Howto-PwauthFilter-PwAuthParameters">PwAuth Parameters</A></LI>
+ <LI><SPAN class="TOCOutline">1.2</SPAN> <A href="#Howto-PwauthFilter-HowtoenablePwAuthFilter">How to enable PwAuth Filter</A></LI>
+ <LI><SPAN class="TOCOutline">1.3</SPAN> <A href="#Howto-PwauthFilter-Howitworks">How it works</A></LI>
+</UL>
+</UL></DIV></DIV>
+
+<H1><A name="Howto-PwauthFilter-PwAuthFilter"></A>PwAuth Filter</H1>
+<P>The purpose of this document is to provide an overview of the PwAuth Filter. PwAuth is a message filter which watches for Session.UP and attempts to<BR>
+authenticate the user by sending a message to the server with the name and password in it. If the server responds, the session is notified with the<BR>
+user name. If the server responds negatively, the session is notified of the failure (using a PwAuthFail event). A transport control may also be sent to<BR>
+force a login or logout or to set the name or password. The name and password are initialized from the uri, or prompted for if not specified.</P>
+
+<H2><A name="Howto-PwauthFilter-PwAuthParameters"></A>PwAuth Parameters</H2>
+
+<P>PwAuth.user - Specify the user name on the uri<BR>
+PwAuth.password - Specify the password on the uri</P>
+
+
+<H2><A name="Howto-PwauthFilter-HowtoenablePwAuthFilter"></A>How to enable PwAuth Filter</H2>
+
+<P>In Listener, change the uri to enable PWAuth Filter</P>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>String uri = "tcp://0.0.0.0:4008?filter=PwAuth"
+</PRE>
+</DIV></DIV>
+
+<P>In client, change the uri to</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>String uri = "tcp://fred:1234@localhost:4008?filter=PwAuth";
+
+where fred is the username
+and 1234 is the password
+
+</PRE>
+</DIV></DIV>
+
+<H2><A name="Howto-PwauthFilter-Howitworks"></A>How it works</H2>
+
+<P>When the session is UP, the client send a PwAuth request to the server. If username/password has not been set on the uri, the PWAuth<BR>
+will send a session query to the client, asking for username/password.</P>
+
+<P>On the server side, PWAuth filter intercepts the request, gets the username/password from the request, package them in a UserPassword Object and sends a<BR>
+session query to the server. In the Server Impl, the logic to authenticate the user can be placed. The return object is OkStatus</P>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>
+public Object _sessionQuery( Object query ) throws Exception
+ {
+ if (query instanceof UserPassword)
+ {
+ OkStatus status = null;
+ UserPassword up = (UserPassword) query;
+ if (up.user.equals( "fred" ) && up.password.equals( "1234" ))
+ {
+ status = new OkStatus( true, "" );
+ System.out.println( " Authentication Passed" );
+ }
+ else
+ {
+ status = new OkStatus( false, "Authentication failed" );
+ System.out.println( " Authentication Failed" );
+ }
+ return status;
+ }
+
+ throw new UnsupportedOperationException( "unknown query: " + query );
+ }
+
+</PRE>
+</DIV></DIV></P></TD></TR></TBODY></TABLE>
+ </DIV>
+
+
+
+ </DIV>
+ </DIV>
+ <!--
+ <div class="footer">
+ Generated by
+ <a href="http://www.atlassian.com/confluence/">Atlassian Confluence</a> (Version: 3.2 Build: 1810 Mar 16, 2010)
+ <a href="http://could.it/autoexport/">Auto Export Plugin</a> (Version: 1.0.0- dkulp)
+ </div>
+ -->
+ </BODY>
+</HTML>
Added: incubator/etch/site/trunk/content/etch/documentation/howto-tls.html
URL: http://svn.apache.org/viewvc/incubator/etch/site/trunk/content/etch/documentation/howto-tls.html?rev=1214782&view=auto
==============================================================================
--- incubator/etch/site/trunk/content/etch/documentation/howto-tls.html (added)
+++ incubator/etch/site/trunk/content/etch/documentation/howto-tls.html Thu Dec 15 14:35:38 2011
@@ -0,0 +1,351 @@
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<HTML>
+ <HEAD>
+ <LINK type="text/css" rel="stylesheet" href="resources/space.css">
+ <STYLE type="text/css">
+ .footer {
+ background-image: url('https://cwiki.apache.org/confluence/images/border/border_bottom.gif');
+ background-repeat: repeat-x;
+ background-position: left top;
+ padding-top: 4px;
+ color: #666;
+ }
+ </STYLE>
+ <SCRIPT type="text/javascript" language="javascript">
+ var hide = null;
+ var show = null;
+ var children = null;
+
+ function init() {
+ /* Search form initialization */
+ var form = document.forms['search'];
+ if (form != null) {
+ form.elements['domains'].value = location.hostname;
+ form.elements['sitesearch'].value = location.hostname;
+ }
+
+ /* Children initialization */
+ hide = document.getElementById('hide');
+ show = document.getElementById('show');
+ children = document.all != null ?
+ document.all['children'] :
+ document.getElementById('children');
+ if (children != null) {
+ children.style.display = 'none';
+ show.style.display = 'inline';
+ hide.style.display = 'none';
+ }
+ }
+
+ function showChildren() {
+ children.style.display = 'block';
+ show.style.display = 'none';
+ hide.style.display = 'inline';
+ }
+
+ function hideChildren() {
+ children.style.display = 'none';
+ show.style.display = 'inline';
+ hide.style.display = 'none';
+ }
+ </SCRIPT>
+ <TITLE>Howto - TLS</TITLE>
+ <META http-equiv="Content-Type" content="text/html;charset=UTF-8"></HEAD>
+ <BODY onload="init()">
+ <DIV id="PageContent">
+ <DIV class="pagecontent">
+ <DIV class="wiki-content">
+
+<TABLE>
+<TR>
+<TD class="" valign="top" width="90%">
+<P><DIV class="navmenu" style="float:right; background:white; margin:3px; padding:3px"><STYLE type="text/css">/*<![CDATA[*/
+div.rbtoc1249351885337 {margin-left: 0px;padding: 0px;}
+div.rbtoc1249351885337 ul {list-style: none;margin-left: 0px;}
+div.rbtoc1249351885337 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</STYLE><DIV class="rbtoc1249351885337">
+<UL>
+ <LI><SPAN class="TOCOutline">1</SPAN> <A href="#Howto-TLS-TLSinEtch">TLS in Etch</A></LI>
+<UL>
+ <LI><SPAN class="TOCOutline">1.1</SPAN> <A href="#Howto-TLS-CertificateManagement">Certificate Management</A></LI>
+ <LI><SPAN class="TOCOutline">1.2</SPAN> <A href="#Howto-TLS-ChangestotheListener">Changes to the Listener</A></LI>
+ <LI><SPAN class="TOCOutline">1.3</SPAN> <A href="#Howto-TLS-ChangestoClient">Changes to Client</A></LI>
+</UL>
+</UL></DIV></DIV>
+
+<H1><A name="Howto-TLS-TLSinEtch"></A>TLS in Etch</H1>
+
+<P>The purpose of this document is to provide a step by step description on how to enable SSL in etch</P>
+
+<H2><A name="Howto-TLS-CertificateManagement"></A>Certificate Management</H2>
+
+<P>Certificates are required to enable encryption of data, maintaining its integrity and optionally providing authentication.</P>
+
+<H3><A name="Howto-TLS-CertificateManagementforJavaServerandJavaClient"></A>Certificate Management for Java Server and Java Client</H3>
+
+
+<H4><A name="Howto-TLS-CreatingServerCertificateusingKeyTool%28Java%29"></A>Creating Server Certificate using KeyTool (Java)</H4>
+
+<P>(Before running keytool make sure java is installed on your machine and is defined in PATH enviorment variable)</P>
+
+<P>This certificate will be used on the machine where the listener is running.</P>
+
+<P><B>keytool -genkey -alias myalias -validity 365 -keystore keys/my.keystore</B></P>
+
+<P>Enter keystore password: abc123<BR>
+What is your first and last name?<BR>
+Unknown: Etch<BR>
+What is the name of your organizational unit?<BR>
+Unknown: CUAE<BR>
+What is the name of your organization?<BR>
+Unknown: Cisco<BR>
+What is the name of your City or Locality?<BR>
+Unknown: Austin<BR>
+What is the name of your State or Province?<BR>
+Unknown: TX<BR>
+What is the two-letter country code for this unit?<BR>
+Unknown: US<BR>
+Is CN=Etch, OU=CUAE, O=Cisco, L=Austin, ST=TX, C=US correct?<BR>
+y</P>
+
+<P>Enter key password for <myalias><BR>
+(RETURN if same as keystore password):</P>
+
+<P>It is preferable that you type in the same password for myalias as you did for keystore.<BR>
+-keystore option allows you to specify the keystore you want to use. In the above example my.keystore is created in the (current directory)/keys</P>
+
+<H4><A name="Howto-TLS-ImportingtheCertificateintoaClientMachine%28Java%29"></A>Importing the Certificate into a Client Machine (Java)</H4>
+
+<P>This section is only required if you want to authenticate the server. If authenticate is not required, please skip this section</P>
+
+<P>In the last section we created a certificate for the machine running the listener. Now the certificate has to be imported into the client machine</P>
+
+<P>First export the certificate created in previous section to a file</P>
+
+<P><B>keytool -export -keystore keys/my.keystore -alias myalias -file server.cer</B></P>
+
+<P>Now copy this certificate to your client machine and import it to a truststore</P>
+
+<P><B>keytool -import -keystore jssecacerts -alias myalias -file server.cer</B></P>
+
+<P>-keystore in this context is the truststore</P>
+
+<H3><A name="Howto-TLS-CertificateManagementforC%23ServerandC%23Client"></A>Certificate Management for C# Server and C# Client</H3>
+
+
+<H4><A name="Howto-TLS-Creatingaservercertificateusingmakecert%28C%23%29"></A>Creating a server certificate using makecert (C#)</H4>
+
+<P>This certificate will be used on the machine where the listener is running.</P>
+
+<P>*makecert -pe -n "CN=Test And Dev Root Authority" -ss my -sr LocalMachine -a sha1 -sky signature -r "Test And Dev Root Authority.cer"* </P>
+<DIV class="panelMacro"><TABLE class="tipMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD><B>Handy Hint</B><BR>You are not required to install Visual Studio on to the CUAE server to get the makecert executable. You should be able to copy the file from a client that has Visual Studio installed and place it on the CUAE server to run the command above. The file can be found in the folloowing directory for a Visual Studio install:<BR>
+C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\Bin\makecert</TD></TR></TABLE></DIV>
+<P>The above command creates a Root certificate. All your personal certificates will extend from this root certificate. So lets create a personal certificate now.<BR>
+<B>makecert -pe -n "CN=gsandhir-wxp02" -ss my -sr LocalMachine -a sha1 -sky exchange -in "Test And Dev Root Authority" -is my -ir LocalMachine -sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12 gsandhir-wxp02.cer</B></P>
+
+<P>If you run up a Certificates MMC at this point, you will be able to see this. However, by default, the Certificates snap-in isn't available as a short cut. Hence, use the following steps:</P>
+<UL>
+ <LI>start/run/mmc</LI>
+ <LI>File/Add-Remove Snap-In</LI>
+ <LI>Click Add</LI>
+ <LI>Select Certificates and click Add</LI>
+ <LI>Select Computer Account and hit Next</LI>
+ <LI>Select Local Computer</LI>
+ <LI>Click Finish</LI>
+ <LI>Click Close</LI>
+ <LI>Click OK</LI>
+</UL>
+
+
+<P>If you expand the console out to Personal/Certificates, you will see your newly created certificates.</P>
+
+<P>In the certificates snap-in, right-click the "Test and Dev Root Authority" certificate and copy it to the "Trusted Root Certification Authorities" node. Once done, if you expand this node, and then select certificates your newly created root cert should be present.</P>
+
+<H4><A name="Howto-TLS-ImportingtheCertificatecreatedusingmakecertintoaClientMachine%28C%23%29"></A>Importing the Certificate created using makecert into a Client Machine (C#)</H4>
+
+<P>This section is only required if you want to authenticate the server. If authentication is not required, please skip this section</P>
+
+<P>First thing we need to do is export the certificate made in the previous step into a file</P>
+
+<P>Run MMC</P>
+<UL>
+ <LI>Add the Certificate snap-in as described in the previous section</LI>
+ <LI>Expand Trusted Root Certification Authorities\Certificates and select the Test And Dev Root Authority we created in the last section</LI>
+ <LI>Right click on the certificate and select All Tasks->Export</LI>
+ <LI>Certificate Export wizard will be launched. Click next</LI>
+ <LI>Make sure you select "No, do not export the private key".</LI>
+ <LI>Keep the default for the Export File Format (DER encoded binary X509)</LI>
+ <LI>Type in any file name and click finish</LI>
+</UL>
+
+
+<P>Now we will copy this file into the client machine and then import it into that machine's certificate store</P>
+<UL>
+ <LI>Run MMC</LI>
+ <LI>Add the Certificate snap-in as described in the previous section</LI>
+ <LI>Select Certificates under Trusted Root Certification Authorities and right click on it and chose All Tasks->Import</LI>
+ <LI>Specify the file name as the certificate we copied from server.</LI>
+ <LI>Chose all the default options and click finish</LI>
+</UL>
+
+
+<H3><A name="Howto-TLS-CertificateManagementforC%23ServerandJavaClient"></A>Certificate Management for C# Server and Java Client</H3>
+
+
+<H4><A name="Howto-TLS-Creatingaservercertificateusingmakecert%28C%23%29"></A>Creating a server certificate using makecert (C#)</H4>
+
+<P>This certificate will be used on the machine where the listener is running.</P>
+
+<P>*makecert -pe -n "CN=TestRoot" -ss my -sr LocalMachine -a sha1 -sky signature -r "TestRoot.cer"* </P>
+<DIV class="panelMacro"><TABLE class="tipMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD><B>Handy Hint</B><BR>You are not required to install Visual Studio on to the CUAE server to get the makecert executable. You should be able to copy the file from a client that has Visual Studio installed and place it on the CUAE server to run the command above. The file can be found in the folloowing directory for a Visual Studio install:<BR>
+C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\Bin\makecert</TD></TR></TABLE></DIV>
+<P>The above command creates a Root certificate. All your personal certificates will extend from this root certificate. So lets create a personal certificate now.<BR>
+<B>makecert -pe -n "CN=Test" -ss my -sr LocalMachine -a sha1 -sky exchange -in "TestRoot" -is my -ir LocalMachine -sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12 Test.cer</B></P>
+
+<P>If you run up a Certificates MMC at this point, you will be able to see this. However, by default, the Certificates snap-in isn't available as a short cut. Hence, use the following steps:</P>
+<UL>
+ <LI>start/run/mmc</LI>
+ <LI>File/Add-Remove Snap-In</LI>
+ <LI>Click Add</LI>
+ <LI>Select Certificates and click Add</LI>
+ <LI>Select Computer Account and hit Next</LI>
+ <LI>Select Local Computer</LI>
+ <LI>Click Finish</LI>
+ <LI>Click Close</LI>
+ <LI>Click OK</LI>
+</UL>
+
+
+<P>If you expand the console out to Personal/Certificates, you will see your newly created certificates.</P>
+
+<P>In the certificates snap-in, right-click the "TestRoot" certificate and copy it to the "Trusted Root Certification Authorities" node. Once done, if you expand this node, and then select certificates your newly created root cert should be present.</P>
+
+<H4><A name="Howto-TLS-ImportingthecertificatetoJavaClient"></A>Importing the certificate to Java Client</H4>
+
+<P>This section is only required if you want to authenticate the server. If authentication is not required, please skip this section</P>
+
+<P>First thing we need to do is export the certificate made in the previous step into a file</P>
+
+<P>Run MMC</P>
+<UL>
+ <LI>Add the Certificate snap-in as described in the previous section</LI>
+ <LI>Expand Trusted Root Certification Authorities\Certificates and select the TestRoot certificate we created in the last section</LI>
+ <LI>Right click on the certificate and select All Tasks->Export</LI>
+ <LI>Certificate Export wizard will be launched. Click next</LI>
+ <LI>Make sure you select "No, do not export the private key".</LI>
+ <LI>Keep the default for the Export File Format (DER encoded binary X509)</LI>
+ <LI>Type in any file name and click finish (for example server.cer)</LI>
+</UL>
+
+
+<P>Now copy this certificate to your client machine and import it to a truststore</P>
+
+<P><B>keytool -import -keystore jssecacerts -alias myalias -file server.cer</B></P>
+
+<P>-keystore in this context is the truststore</P>
+
+<H2><A name="Howto-TLS-ChangestotheListener"></A>Changes to the Listener</H2>
+
+
+<H3><A name="Howto-TLS-JavaListener"></A>Java Listener</H3>
+
+
+<H4><A name="Howto-TLS-VMArguments"></A>VM Arguments</H4>
+
+<P>Before we run the listener we need to specify the keystore, keystore password through the VM arguments</P>
+
+<P>For example</P>
+
+<P>-Djavax.net.ssl.keyStore=C:\MyKeyTools\keys\my.keystore<BR>
+-Djavax.net.ssl.keyStorePassword=abc123<BR>
+-Djavax.net.ssl.keyPairPassword=xyz123 ( optional )</P>
+
+<P>-Djavax.net.ssl.keyStore corresponds to the keystore created while using "keytools -genkey" command (see Creating Server Certificate using KeyTool section)<BR>
+-Djavax.net.ssl.keyStorePassword=abc123 corresponds to the keystore password used<BR>
+-Djavax.net.ssl.keyPairPassword=xyz123 is only REQUIRED if the keypair password is different than the keystore password</P>
+
+<H4><A name="Howto-TLS-ChangestoCode"></A>Changes to Code</H4>
+
+<P>The only change is to use tls as the protocol instead of tcp.</P>
+
+<P>Hence instead on specifying uri as</P>
+
+<P>String uri = "tcp://0.0.0.0:4001";</P>
+
+<P>we will now specify it as</P>
+
+<P>String uri = "tls://0.0.0.0:4001";</P>
+
+<H3><A name="Howto-TLS-C%23Listener"></A>C# Listener</H3>
+
+<P>The only change is in the URI</P>
+
+<P>Before</P>
+
+<P>string uri = "tcp://0.0.0.0:4001";</P>
+
+<P>After TLS</P>
+
+<P>string uri = "tls://localhost:4001?TlsConnection.certName=gsandhir-wxp02";</P>
+
+<P>Please remember in order to run in secure mode the certificate name has to be specified on the uri. The name of the certificate corresponds to the CN argument we specified in makecert (see section "Creating a server certificate using makecert (C#)". The example in that section created a certificate with -n "CN=gsandhir-wxp02", hence in the uri we pass in the certName as gsandhir-wxp02.</P>
+
+<H2><A name="Howto-TLS-ChangestoClient"></A>Changes to Client</H2>
+
+
+<H3><A name="Howto-TLS-JavaClient"></A>Java Client</H3>
+
+<P>The client can chose whether it wants to authenticate the server or not</P>
+
+<H4><A name="Howto-TLS-Changeswhenauthenticationisrequired"></A>Changes when authentication is required</H4>
+
+<P>Before we run the client we need to pass in the location of the truststore as a VM argument</P>
+
+<P>-Djavax.net.ssl.trustStore=C:\MyKeyTools\deftruststore</P>
+
+<P>-Djavax.net.ssl.trustStore - Corresponds to the keystore location where server certificate was imported (see section "Importing the Certificate into a Client Machine (Java)")</P>
+
+<P>Change the uri in the code to String uri = "tls://localhost:4001";</P>
+
+<H4><A name="Howto-TLS-Changeswhenauthenticationisnotrequired"></A>Changes when authentication is not required</H4>
+
+<P>In this case we do not need to specify the truststore location.</P>
+
+<P>However in the uri we must specify explicitly that authentication should be switched off</P>
+
+<P>String uri = "tls://localhost:4001?TlsConnection.authReqd=false";</P>
+
+<H3><A name="Howto-TLS-C%23Client"></A>C# Client</H3>
+
+<P>Similar to Java, client can chose whether it wants to authenticate the server or not</P>
+
+<H4><A name="Howto-TLS-Changeswhenauthenticationisrequired"></A>Changes when authentication is required</H4>
+
+<P>The uri in the client code will appear as following</P>
+
+<P>string uri = "tls://localhost:4001?TlsConnection.certName=gsandhir-wxp02";</P>
+
+<P>As mentioned in the listener C# section, the certificate name must correspond to the CN name specified when creating a certificate.</P>
+
+<H4><A name="Howto-TLS-Changeswhenauthenticationisnotrequired"></A>Changes when authentication is not required</H4>
+
+<P>The uri in the client code will appear as following</P>
+
+<P>String uri = "tls://localhost:4001?TlsConnection.authReqd=false";</P></P></TD></TR></TBODY></TABLE>
+ </DIV>
+
+
+
+ </DIV>
+ </DIV>
+ <!--
+ <div class="footer">
+ Generated by
+ <a href="http://www.atlassian.com/confluence/">Atlassian Confluence</a> (Version: 3.2 Build: 1810 Mar 16, 2010)
+ <a href="http://could.it/autoexport/">Auto Export Plugin</a> (Version: 1.0.0- dkulp)
+ </div>
+ -->
+ </BODY>
+</HTML>
Added: incubator/etch/site/trunk/content/etch/documentation/javascript-language-binding.html
URL: http://svn.apache.org/viewvc/incubator/etch/site/trunk/content/etch/documentation/javascript-language-binding.html?rev=1214782&view=auto
==============================================================================
--- incubator/etch/site/trunk/content/etch/documentation/javascript-language-binding.html (added)
+++ incubator/etch/site/trunk/content/etch/documentation/javascript-language-binding.html Thu Dec 15 14:35:38 2011
@@ -0,0 +1,367 @@
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<HTML>
+ <HEAD>
+ <LINK type="text/css" rel="stylesheet" href="resources/space.css">
+ <STYLE type="text/css">
+ .footer {
+ background-image: url('https://cwiki.apache.org/confluence/images/border/border_bottom.gif');
+ background-repeat: repeat-x;
+ background-position: left top;
+ padding-top: 4px;
+ color: #666;
+ }
+ </STYLE>
+ <SCRIPT type="text/javascript" language="javascript">
+ var hide = null;
+ var show = null;
+ var children = null;
+
+ function init() {
+ /* Search form initialization */
+ var form = document.forms['search'];
+ if (form != null) {
+ form.elements['domains'].value = location.hostname;
+ form.elements['sitesearch'].value = location.hostname;
+ }
+
+ /* Children initialization */
+ hide = document.getElementById('hide');
+ show = document.getElementById('show');
+ children = document.all != null ?
+ document.all['children'] :
+ document.getElementById('children');
+ if (children != null) {
+ children.style.display = 'none';
+ show.style.display = 'inline';
+ hide.style.display = 'none';
+ }
+ }
+
+ function showChildren() {
+ children.style.display = 'block';
+ show.style.display = 'none';
+ hide.style.display = 'inline';
+ }
+
+ function hideChildren() {
+ children.style.display = 'none';
+ show.style.display = 'inline';
+ hide.style.display = 'none';
+ }
+ </SCRIPT>
+ <TITLE>Javascript Language Binding</TITLE>
+ <META http-equiv="Content-Type" content="text/html;charset=UTF-8"></HEAD>
+ <BODY onload="init()">
+ <DIV id="PageContent">
+ <DIV class="pagecontent">
+ <DIV class="wiki-content">
+<TABLE
+<TR>
+<TD class="" valign="top" width="90%">
+<P><DIV class="navmenu" style="float:right; background:white; margin:3px; padding:3px"><STYLE type="text/css">/*<![CDATA[*/
+div.rbtoc1250891670060 {margin-left: 0px;padding: 0px;}
+div.rbtoc1250891670060 ul {list-style: none;margin-left: 0px;}
+div.rbtoc1250891670060 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</STYLE><DIV class="rbtoc1250891670060">
+<UL>
+ <LI><SPAN class="TOCOutline">1</SPAN> <A href="#JavascriptLanguageBinding-Overview">Overview</A></LI>
+ <LI><SPAN class="TOCOutline">2</SPAN> <A href="#JavascriptLanguageBinding-Ideals">Ideals</A></LI>
+ <LI><SPAN class="TOCOutline">3</SPAN> <A href="#JavascriptLanguageBinding-MappingEtchIDLtoJavascript">Mapping Etch IDL to Javascript</A></LI>
+<UL>
+ <LI><SPAN class="TOCOutline">3.1</SPAN> <A href="#JavascriptLanguageBinding-Serverdirectedmethod">Server-directed method</A></LI>
+ <LI><SPAN class="TOCOutline">3.2</SPAN> <A href="#JavascriptLanguageBinding-Serverdirectedmethodthatusesstructs">Server-directed method that uses structs</A></LI>
+ <LI><SPAN class="TOCOutline">3.3</SPAN> <A href="#JavascriptLanguageBinding-Serverdirectedmethodwithexception">Server-directed method with exception</A></LI>
+ <LI><SPAN class="TOCOutline">3.4</SPAN> <A href="#JavascriptLanguageBinding-Clientdirectedmethod">Client-directed method</A></LI>
+ <LI><SPAN class="TOCOutline">3.5</SPAN> <A href="#JavascriptLanguageBinding-Clientdirectedmethodwithareturn">Client-directed method with a return</A></LI>
+ <LI><SPAN class="TOCOutline">3.6</SPAN> <A href="#JavascriptLanguageBinding-Clientdirectedmethodthatdefinesanexception">Client-directed method that defines an exception</A></LI>
+</UL>
+ <LI><SPAN class="TOCOutline">4</SPAN> <A href="#JavascriptLanguageBinding-CurrentState">Current State</A></LI>
+ <LI><SPAN class="TOCOutline">5</SPAN> <A href="#JavascriptLanguageBinding-Roadmap">Roadmap</A></LI>
+</UL></DIV></DIV>
+
+<H2><A name="JavascriptLanguageBinding-Overview"></A>Overview</H2>
+
+<P>The Javascript binding, like other Etch language bindings, aims to allow developers a way to access Etch-based services in a manner which is as natural to the developer as possible. Ideally, this means that by simply looking at an Etch IDL, one should be able intuit how one would invoke the methods of such a service with understanding just a few simple conventions.</P>
+
+<P>Since most developers speak code, let's look at some examples of what this really means for Javascript.</P>
+
+<P>Consider a simple, server-directed <B>add</B> method defined in an Etch IDL file:</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>@Direction(server)
+int add(int arg1, int arg2)
+</PRE>
+</DIV></DIV>
+<P>Then we consider how one would invoke that method in a Javascript script:</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>svc.add({
+ arg1: 1,
+ arg2: 2,
+ onSuccess: function(returnValue)
+ {
+ alert ("Got a result: " + returnValue);
+ },
+ onError: function(error)
+ {
+ alert("failure");
+ }
+});
+</PRE>
+</DIV></DIV>
+<P>Using the above example, let's take a second to talk about how a method in an Etch IDL translates into a Javascript method.</P>
+
+<P>The <B>svc</B> variable in the above snippet is the object which represents the client-side reference to the service. There are just a few lines of boilerplate service initialization not shown here, but all one needs to know is that every method associated with the Etch service is represented as a function on this <B>svc</B> object, such as the <B>add</B> method defined in the Etch IDL above.</P>
+
+<P>The next convention in use here is that each argument is passed into the method as a named parameter. In this example, that's the <B>arg1:</B> and <B>arg2:</B>. If we had omitted <B>arg1</B>, <B>arg2</B>, or both, nulls would have been passed to the server for those omitted values.</P>
+
+<P>Finally, every server-directed method support a <B>onSuccess</B> and <B>onError</B> argument, which expect you to pass a function. These functions serve as callbacks that are fired once the method has completed. The <B>onSuccess</B> callback is invoked if the operation completed successfully. Passed back as the only argument to this <B>onSuccess</B> callback is the return value of the method (if void is the return then no argument is passed). The <B>onError</B> callback is invoked if the operation did not complete successfully; for instance, if the method threw an exception, or if communication was interrupted between client and server on that method call. Note that we use callbacks instead of the return value of the <B>svc.add</B> method because Javascript is implemented as a single-threaded language in every browser. This thread is shared between the browser UI and the Javascript script code, so we must not block the browser waiting on a response from the server.</
P>
+
+<H2><A name="JavascriptLanguageBinding-Ideals"></A>Ideals</H2>
+
+<P>There are a number of considerations one must make when dealing with browsers, Javascript, and the web in general. The ideals below represent the general mindset and direction of the binding. At this point in time, these ideals are not necessarily fully implemented.</P>
+<UL>
+ <LI><B>No dependency on browser plugins</B> – such as applets or Flash</LI>
+ <LI><B>Cross-browser support</B></LI>
+ <LI><B>Small Javascript script size</B> – we don't want to ruin your user download experience</LI>
+ <LI><B>No Javascript type pollution</B> – we don't add fields to native Javascript types, such as Object</LI>
+ <LI><B>Hide the transport</B> – Etch is transport agnostic, so you should not see any HTTP requests/responses in your code. This is important; what if someday there is an alternate Etch Javascript implementation which uses Flash sockets? In such a case, ideally your code could use either transport with just a simple switch during initialization</LI>
+ <LI><B>Hide the encoding</B> – Etch is encoding agnostic. There may be valid reasons to encode messages in XML, JSON, or something else over the transport, but your code should not be exposed to these technology choices</LI>
+ <LI><B>Client-directed messages must be supported</B> – we have first implemented a COMET (alternatively known as hang-polling or long-polling) mechanism within the underlying transport to achieve low-latency, but it only makes sense to allow a web page to use polling instead, if great latency is not demanded</LI>
+ <LI><B>Support all popular browser-abstraction libraries</B> – jQuery, prototype, and other libraries do a great job of abstracting away the complexities of browser-specific differences for a number of AJAX operations. These libraries are becoming indispensable in any rich web application, and ideally, this binding can detect which library is in use and use it, rather than this binding force you to include an entire library to your page when the one already in your page would work just as well</LI>
+ <LI><B>Small server-side footprint</B> – to achieve this, we need to support leveraging <B>your</B> already-deployed web server technology, whatever that may be</LI>
+ <LI><B>Support any Etch service</B> – This guided the use of XMLHttpRequest instead of <script> tag or iFrame requests, since an XMLHttpRequest can POST huge amounts of data, whereas <script>/iFrame requests can not send much data since they only support GET. This means that a server-side proxy is very likely required since XMLHttpRequest has cross-domain request restrictions, but, the overall solution has less restrictions on what types of services can be consumed by this binding without heartache</LI>
+ <LI><B>Namespacing must be supported</B> – Etch is inherently namespaced, and maximum compatibility with all services require this binding be namespaced. When using the binding, it should be noted that namespaces are hidden from the developer as much as possible without sacrificing flexibility</LI>
+</UL>
+
+
+<H2><A name="JavascriptLanguageBinding-MappingEtchIDLtoJavascript"></A>Mapping Etch IDL to Javascript</H2>
+<P>Every Etch IDL construct should have a intuitive analogy in Javascript. This section details those mappings.</P>
+
+<H3><A name="JavascriptLanguageBinding-Serverdirectedmethod"></A>Server-directed method</H3>
+
+<P>Etch IDL</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>@Direction(server)
+int add(int arg1, int arg2)
+</PRE>
+</DIV></DIV>
+
+<P>Javascript</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>svc.add({
+ arg1: 1,
+ arg2: 2,
+ onSuccess: function(returnValue)
+ {
+ alert ("Got a result: " + returnValue);
+ },
+ onError: function(error)
+ {
+ alert("failure");
+ }
+});
+</PRE>
+</DIV></DIV>
+
+<H3><A name="JavascriptLanguageBinding-Serverdirectedmethodthatusesstructs"></A>Server-directed method that uses structs</H3>
+
+<P>Etch IDL</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>
+module etch.examples
+
+service Calculator
+{
+ struct Values
+ {
+ int arg1,
+ int arg2
+ }
+
+ struct AddResult
+ {
+ int addResult
+ }
+
+ @Direction(server)
+ AddResult add(Values toBeAdded)
+}
+</PRE>
+</DIV></DIV>
+
+<P>Javascript</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>
+var values = new etch.examples.Calculator.Values();
+values.arg1 = 1;
+values.arg2 = 2;
+
+svc.add({
+ toBeAdded: values,
+ onSuccess: function(returnValue)
+ {
+ // returnValue instanceof etch.examples.Calculator.AddResult == true
+ alert ("Got a result: " + returnValue.addResult);
+ },
+ onError: function(error)
+ {
+ alert("failure");
+ }
+});
+</PRE>
+</DIV></DIV>
+
+<H3><A name="JavascriptLanguageBinding-Serverdirectedmethodwithexception"></A>Server-directed method with exception</H3>
+
+<P>Etch IDL</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>
+module etch.examples
+
+service Calculator
+{
+ exception OverflowException
+ {
+ string message
+ }
+
+ @Direction(server)
+ int add(int arg1, int arg2) throws OverflowException
+}
+</PRE>
+</DIV></DIV>
+
+<P>Javascript</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>svc.add({
+ arg1: 1,
+ arg2: 2,
+ onSuccess: function(returnValue)
+ {
+ alert ("Got a result: " + returnValue);
+ },
+ onError: function(error)
+ {
+ if(error instanceof etch.examples.Calculator.OverflowException)
+ {
+ alert("Overflow exception. Message: " + error.message);
+ }
+ }
+});
+</PRE>
+</DIV></DIV>
+
+<H3><A name="JavascriptLanguageBinding-Clientdirectedmethod"></A>Client-directed method</H3>
+
+<P>Etch IDL</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>/** Example method server tells client about some state change */
+@Direction(client)
+void stateChange(string username, boolean online)
+</PRE>
+</DIV></DIV>
+
+<P>Javascript</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>svc.callbacks.stateChange = function (username, online)
+{
+ // define your custom logic in this method, to indicate
+ // what happens when the server invokes 'stateChange'
+}
+</PRE>
+</DIV></DIV>
+
+<H3><A name="JavascriptLanguageBinding-Clientdirectedmethodwithareturn"></A>Client-directed method with a return</H3>
+
+<P>Etch IDL</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>/** Example method server tells client about some state change, client acks it */
+@Direction(client)
+boolean stateChange(string username, boolean online)
+</PRE>
+</DIV></DIV>
+
+<P>Javascript</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>svc.callbacks.stateChange = function (username, online)
+{
+ // because stateChange defines a boolean return, we should return a value
+ return true;
+}
+</PRE>
+</DIV></DIV>
+
+<H3><A name="JavascriptLanguageBinding-Clientdirectedmethodthatdefinesanexception"></A>Client-directed method that defines an exception</H3>
+
+<P>Etch IDL</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>/** Example method server tells client about some state change, client can throw exception */
+module etch.examples
+
+service Chat
+{
+ struct NotSupportedException
+ {
+ string reason
+ }
+
+ @Direction(client)
+ boolean stateChange(string username, boolean online) throws NotSupportedException
+}
+</PRE>
+</DIV></DIV>
+
+<P>Javascript</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>svc.callbacks.stateChange = function (username, online)
+{
+ // say we want to let the server know that this client does not support
+ // the stateChange callback
+
+ var notSupported = etch.examples.Chat.NotSupportedException();
+ notSupported.reason = "Not currently supported.";
+
+ throw notSupported;
+}
+</PRE>
+</DIV></DIV>
+
+<H2><A name="JavascriptLanguageBinding-CurrentState"></A>Current State</H2>
+<UL>
+ <LI>Only one server-side implementation currently, built for C#/.NET using System.Net.HttpListener. SVN location: <A href="https://svn.apache.org/repos/asf/incubator/etch/branches/etch-javascript" class="external-link" rel="nofollow">https://svn.apache.org/repos/asf/incubator/etch/branches/etch-javascript</A></LI>
+ <LI>Support for the following types: <B>boolean</B>, <B>int</B>, <B>byte</B>, <B>short</B>, <B>long</B>, <B>string</B>, <B>List</B>, <B>struct</B>, <B>datetime</B></LI>
+ <LI>Exceptions are supported.</LI>
+ <LI>Notification is given on session "DOWN" and session "UP"</LI>
+ <LI>jQuery is supported.</LI>
+ <LI>Etch compiler successfully generates Javascript stub code (etch -b javascript)</LI>
+</UL>
+
+
+<H2><A name="JavascriptLanguageBinding-Roadmap"></A>Roadmap</H2>
+<UL>
+ <LI>Build up unit tests while also refactoring/cleaning up existing code</LI>
+ <LI>Work on scale for C# implementation (need to vet System.Net.HttpListener sooner rather than later)</LI>
+ <LI>Implement the following types: Map and Set</LI>
+ <LI>Implement onUnload handler logic to keep browser resource usage low</LI>
+ <LI>Implement cookie session handling (currently the session dies when window is closed)</LI>
+ <LI>Add support for another browser-abstraction library, such as prototype.</LI>
+ <LI>Implement Authorize on client.</LI>
+ <LI>Assuming C# implementation is stable and mostly complete, implement Java implementation (presumably using Jetty).</LI>
+</UL>
+</P></TD></TR></TBODY></TABLE>
+ </DIV>
+
+
+
+ </DIV>
+ </DIV>
+ <!--
+ <div class="footer">
+ Generated by
+ <a href="http://www.atlassian.com/confluence/">Atlassian Confluence</a> (Version: 3.2 Build: 1810 Mar 16, 2010)
+ <a href="http://could.it/autoexport/">Auto Export Plugin</a> (Version: 1.0.0- dkulp)
+ </div>
+ -->
+ </BODY>
+</HTML>