You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@etch.apache.org by bu...@apache.org on 2011/12/15 15:36:05 UTC
svn commit: r800281 [1/5] - in /websites/staging/etch/trunk/content/etch: ./
documentation/ documentation/architecture.data/
documentation/howto-logger-filter.data/ documentation/resources/
Author: buildbot
Date: Thu Dec 15 14:36:04 2011
New Revision: 800281
Log:
Staging update by buildbot
Added:
websites/staging/etch/trunk/content/etch/documentation/
websites/staging/etch/trunk/content/etch/documentation/architecture.data/
websites/staging/etch/trunk/content/etch/documentation/architecture.data/Datagram.png (with props)
websites/staging/etch/trunk/content/etch/documentation/architecture.data/Datagram.png.jpeg (with props)
websites/staging/etch/trunk/content/etch/documentation/architecture.data/EtchClient3.png (with props)
websites/staging/etch/trunk/content/etch/documentation/architecture.data/EtchClient3.png.jpeg (with props)
websites/staging/etch/trunk/content/etch/documentation/architecture.data/EtchService1.png (with props)
websites/staging/etch/trunk/content/etch/documentation/architecture.data/EtchService1.png.jpeg (with props)
websites/staging/etch/trunk/content/etch/documentation/architecture.html
websites/staging/etch/trunk/content/etch/documentation/c-binding-tips-tricks.html
websites/staging/etch/trunk/content/etch/documentation/compiler-users-guide.html
websites/staging/etch/trunk/content/etch/documentation/csharp-binding-users-guide.html
websites/staging/etch/trunk/content/etch/documentation/documentation.html
websites/staging/etch/trunk/content/etch/documentation/etch-binary-protocol.html
websites/staging/etch/trunk/content/etch/documentation/example-hello-world.html
websites/staging/etch/trunk/content/etch/documentation/examples.html
websites/staging/etch/trunk/content/etch/documentation/generated-code-users-guide.html
websites/staging/etch/trunk/content/etch/documentation/howto-keepalive-filter.html
websites/staging/etch/trunk/content/etch/documentation/howto-logger-filter.data/
websites/staging/etch/trunk/content/etch/documentation/howto-logger-filter.data/FileRename.JPG (with props)
websites/staging/etch/trunk/content/etch/documentation/howto-logger-filter.data/FileRename.JPG.jpeg (with props)
websites/staging/etch/trunk/content/etch/documentation/howto-logger-filter.html
websites/staging/etch/trunk/content/etch/documentation/howto-pwauth-filter.html
websites/staging/etch/trunk/content/etch/documentation/howto-tls.html
websites/staging/etch/trunk/content/etch/documentation/javascript-language-binding.html
websites/staging/etch/trunk/content/etch/documentation/language-reference.html
websites/staging/etch/trunk/content/etch/documentation/overview.html
websites/staging/etch/trunk/content/etch/documentation/resources/
websites/staging/etch/trunk/content/etch/documentation/resources/space.css
websites/staging/etch/trunk/content/etch/documentation/setup-guide-for-users.html
Modified:
websites/staging/etch/trunk/content/etch/documentation.html
Modified: websites/staging/etch/trunk/content/etch/documentation.html
==============================================================================
--- websites/staging/etch/trunk/content/etch/documentation.html (original)
+++ websites/staging/etch/trunk/content/etch/documentation.html Thu Dec 15 14:36:04 2011
@@ -80,7 +80,25 @@
</div>
<div id="content">
<h1 id="documentation">Documentation</h1>
-<p>We are currently working on a restructuring and expansion of the Etch documentation. In the meanwhile you can use the existing documentation pages available at <a href="https://cwiki.apache.org/ETCH/documentation.html">https://cwiki.apache.org/ETCH/documentation.html</a>.</p>
+<p><em>We are currently working on a restructuring and expansion of the Etch documentation. In the meanwhile you can use the existing documentation embedded below.</em></p>
+<script language="javascript">
+ function resizeIframe() {
+ //get height of page
+
+var height = window.frames.docFrame.document.getElementById("PageContent").scrollHeight;
+ var width = window.frames.docFrame.document.getElementById("PageContent").scrollWidth;
+ height += 60;
+ if (height < 600) {
+ height = 600;
+ }
+ document.getElementById("docFrame").height = height;
+ document.getElementById("docFrame").width = width;
+
+}
+ window.onresize=resizeIframe;
+</script>
+
+<iframe frameborder="0" id="docFrame" name="docFrame" src="documentation/documentation.html" width="99%" onload="resizeIframe()"/>
</div>
<div class="clear"></div>
Added: websites/staging/etch/trunk/content/etch/documentation/architecture.data/Datagram.png
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/etch/trunk/content/etch/documentation/architecture.data/Datagram.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: websites/staging/etch/trunk/content/etch/documentation/architecture.data/Datagram.png.jpeg
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/etch/trunk/content/etch/documentation/architecture.data/Datagram.png.jpeg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: websites/staging/etch/trunk/content/etch/documentation/architecture.data/EtchClient3.png
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/etch/trunk/content/etch/documentation/architecture.data/EtchClient3.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: websites/staging/etch/trunk/content/etch/documentation/architecture.data/EtchClient3.png.jpeg
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/etch/trunk/content/etch/documentation/architecture.data/EtchClient3.png.jpeg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: websites/staging/etch/trunk/content/etch/documentation/architecture.data/EtchService1.png
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/etch/trunk/content/etch/documentation/architecture.data/EtchService1.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: websites/staging/etch/trunk/content/etch/documentation/architecture.data/EtchService1.png.jpeg
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/etch/trunk/content/etch/documentation/architecture.data/EtchService1.png.jpeg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: websites/staging/etch/trunk/content/etch/documentation/architecture.html
==============================================================================
--- websites/staging/etch/trunk/content/etch/documentation/architecture.html (added)
+++ websites/staging/etch/trunk/content/etch/documentation/architecture.html Thu Dec 15 14:36:04 2011
@@ -0,0 +1,214 @@
+
+<!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>Architecture</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.rbtoc1249351873287 {margin-left: 0px;padding: 0px;}
+div.rbtoc1249351873287 ul {list-style: none;margin-left: 0px;}
+div.rbtoc1249351873287 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</STYLE><DIV class="rbtoc1249351873287">
+<UL>
+ <LI><SPAN class="TOCOutline">1</SPAN> <A href="#Architecture-EtchTheArchitecture">Etch The Architecture</A></LI>
+<UL>
+ <LI><SPAN class="TOCOutline">1.1</SPAN> <A href="#Architecture-EtchClientArchitecture">Etch Client Architecture</A></LI>
+ <LI><SPAN class="TOCOutline">1.2</SPAN> <A href="#Architecture-EtchServiceArchitecture">Etch Service Architecture</A></LI>
+ <LI><SPAN class="TOCOutline">1.3</SPAN> <A href="#Architecture-DatagramBasedTransport">Datagram Based Transport</A></LI>
+ <LI><SPAN class="TOCOutline">1.4</SPAN> <A href="#Architecture-CoreModules">Core Modules</A></LI>
+</UL>
+</UL></DIV></DIV>
+
+<H1><A name="Architecture-EtchTheArchitecture"></A>Etch The Architecture</H1>
+
+<H2><A name="Architecture-EtchClientArchitecture"></A>Etch Client Architecture</H2>
+
+<P><SPAN class="image-wrap" style=""><IMG src="architecture.data/EtchClient3.png" style="border: 0px solid black"></SPAN></P>
+
+
+<H2><A name="Architecture-EtchServiceArchitecture"></A>Etch Service Architecture</H2>
+
+<P><SPAN class="image-wrap" style=""><IMG src="architecture.data/EtchService1.png" style="border: 0px solid black"></SPAN></P>
+
+
+<H2><A name="Architecture-DatagramBasedTransport"></A>Datagram Based Transport</H2>
+<P>For datagram based protocol like <B>UDP</B>.</P>
+
+<P><SPAN class="image-wrap" style=""><IMG src="architecture.data/Datagram.png" style="border: 0px solid black"></SPAN></P>
+
+
+<H2><A name="Architecture-CoreModules"></A>Core Modules</H2>
+
+<H3><A name="Architecture-Listener"></A>Listener </H3>
+
+<P>The listener for a transport accepts a connection and constructs a new server session to process messages on that connection for that session. In the case of TCP, the listener would normally be a TCP listening socket. For UDP, it might be an unconnected datagram socket </P>
+
+<H3><A name="Architecture-ValueFactory"></A>Value Factory</H3>
+
+<P>The value factory is the repository of the compiler generated service meta-data and methods for serializing and de-serializing custom data objects.</P>
+
+<H3><A name="Architecture-OutOfBandMessageHandler"></A>Out-Of-Band Message Handler</H3>
+
+<P>Normally the client or server implementation, the out-of-band message handler is the last handler in a chain which originates at the lowest level of the transport stack. Transport messages flow up the stack until someone handles them or they get to the top of the stack where the client or server implementation handles them. Transport messages are not the same as service messages, in that they communicate information about the transport stack itself.</P>
+
+<H3><A name="Architecture-StubClient"></A>Stub Client</H3>
+
+<P>The stub client accepts service messages not otherwise distributed to mailboxes by the mailbox manager, turning them into calls on the client implementation where they are handled.</P>
+
+<H3><A name="Architecture-StubServer"></A>Stub Server</H3>
+
+<P>The stub server accepts service messages not otherwise handled by the mailbox manager, turning them into calls on the server implementation where they are handled.</P>
+
+<H3><A name="Architecture-RemoteClient"></A>Remote Client</H3>
+
+<P>The remote client implements the client interface turning method calls into messages which are passed across the network to the stub client.</P>
+
+<H3><A name="Architecture-RemoteServer"></A>Remote Server</H3>
+
+<P>The remote server implements the server interface turning method calls into messages which are passed across the network to the stub server.</P>
+
+<H3><A name="Architecture-MailboxManager"></A>Mailbox Manager</H3>
+
+<P>When a call is made, the mailbox manager allocates a mailbox and ties it to the message id of the resulting message before it is sent. The mailbox manager then watches incoming messages, grabbing those that are responses and delivering them to their associated mailboxes.</P>
+
+<H3><A name="Architecture-FilterChain"></A>Filter Chain</H3>
+
+<P>The filters get to watch, edit, or intercept service messages as they flow up and down the transport stack. Filters might also originate their own messages, originate or intercept out-of-band transport messages, and carry on a dialog with filters on the remote end of a session.</P>
+
+<UL>
+ <LI>Auth - the auth filter might add authentication data to outgoing messages and process authentication data on incoming messages when using a session based on a packet protocol; it might also dialog with an auth filter on the remote side to authenticate session based on a stream protocol.</LI>
+</UL>
+
+
+<UL>
+ <LI>Log - records the incoming and outgoing messages.</LI>
+</UL>
+
+
+<UL>
+ <LI>Session - when using a shared packet protocol, segregates the packets by session much like mailbox manager does.</LI>
+</UL>
+
+
+<UL>
+ <LI>Throttle - limits the amount of traffic on a particular session.</LI>
+</UL>
+
+
+<UL>
+ <LI>Reliable - adds reliability to an unreliable connection.</LI>
+</UL>
+
+
+<UL>
+ <LI>Security - helper filter for Packet Layer Security. Assists with key changes.</LI>
+</UL>
+
+
+<UL>
+ <LI>KeepAlive - periodic message to keep the connection open / detect connection failure.</LI>
+</UL>
+
+
+<UL>
+ <LI>RemoteMonitor - records the incoming and outgoing messages to a remote service.</LI>
+</UL>
+
+
+<UL>
+ <LI>QueuedOutput - used to queue outgoing packets for later delivery when it is important to not delay the sender.</LI>
+</UL>
+
+
+<H3><A name="Architecture-Messagizer"></A>Messagizer</H3>
+
+<P>The Messagizer intercepts messages flowing down the transport stack (say, from a filter or Mailbox Manager), reformats them into packets, and delivers them to a packet source for transport to the remote end of a session. Packets flowing up the transport stack are also reformatted into messages and delivered to a message handler (say, to a filter or Mailbox Manager). The message formatter is pluggable.</P>
+
+<H3><A name="Architecture-Packetizer"></A>Packetizer</H3>
+
+<P>The Packetizer intercepts packets flowing down the transport stack (say, from Messagizer), reformats them into data, and delivers them to a data source for transport to the remote end of a session. Data flowing up the transport stack are also reformatted into packets and delivered to a packet handler (say, to Messagizer).</P>
+
+<H3><A name="Architecture-TransportLayerSecurity"></A>Transport Layer Security</H3>
+
+<P>Security encryption and message authentication which prevents snooping or tampering with the data stream.</P>
+
+<H3><A name="Architecture-StreamProtocol"></A>Stream Protocol</H3>
+
+<P>A stream protocol such as TCP.</P>
+
+<H3><A name="Architecture-OptionalPacketOrientedProtocol"></A>Optional Packet Oriented Protocol</H3>
+
+<P>If a packet oriented protocol is needed, the bottom three modules (Packetizer, Transport Layer Security, and Stream Protocol) are replaced with Packet Layer Security and Packet Protocol. These two modules serve an equivalent purpose. Care needs to be taken to manage the session, in particular session life cycle.</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: websites/staging/etch/trunk/content/etch/documentation/c-binding-tips-tricks.html
==============================================================================
--- websites/staging/etch/trunk/content/etch/documentation/c-binding-tips-tricks.html (added)
+++ websites/staging/etch/trunk/content/etch/documentation/c-binding-tips-tricks.html Thu Dec 15 14:36:04 2011
@@ -0,0 +1,331 @@
+
+<!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>C Binding Tips & Tricks</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>
+ <H1><A name="CBindingTips%26Tricks-UsingtheCBinding"></A>Using the C Binding</H1>
+
+<P>This guide uses "xxx" as the service name. Substitute with the service name from your etch file.</P>
+
+<H2><A name="CBindingTips%26Tricks-Generatedcode"></A>Generated code</H2>
+
+<P>The C Binding compiler is called using</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+etch -b c -d . -w INTF,MAIN,IMPL,CLIENT,SERVER xxxNSDL.etch
+</PRE>
+</DIV></DIV>
+
+<P>It generates code for both sides (client and server). The main files you need to change manually to add your implementation are:</P>
+
+<DIV class="table-wrap">
+<TABLE class="confluenceTable"><TBODY>
+<TR>
+<TH class="confluenceTh"> File </TH>
+<TH class="confluenceTh"> Function </TH>
+</TR>
+<TR>
+<TD class="confluenceTd"> xxx_client_main.c </TD>
+<TD class="confluenceTd"> main method of client, starts runtime, connects to server, calls of server methods, disconnect, destroy runtime </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> xxx_listener_main.c </TD>
+<TD class="confluenceTd"> main method of server, starts runtime, waits for calls </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> xxx_server_impl.c/.h </TD>
+<TD class="confluenceTd"> implementations of server directed methods </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> xxx_client_impl.c/.h </TD>
+<TD class="confluenceTd"> implementations of client directed methods </TD>
+</TR>
+</TBODY></TABLE>
+</DIV>
+
+
+<H2><A name="CBindingTips%26Tricks-Howtoimplementamethodontheserver%2Fontheclient"></A>How to implement a method on the server / on the client</H2>
+
+<P>The following steps describe implementation of server-directed methods. Since Etch is symmetric, the client directed functions are implemented exactly the<BR>
+same way in the client-related generated files.</P>
+
+<P>Assume you have an IDL containing</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+ @Direction(server)
+ <SPAN class="code-object">int</SPAN> simpleFunction(<SPAN class="code-object">int</SPAN> x)
+</PRE>
+</DIV></DIV>
+
+<UL>
+ <LI>open xxx_server_impl.c</LI>
+ <LI>declare an implementation of simpleFunction,e.g.:
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+etch_int32* simpleFunctionImpl(void* thisx, etch_int32* x);
+</PRE>
+</DIV></DIV>
+<DIV class="panelMacro"><TABLE class="noteMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD>You can get the desired function signatures from xxx_interface.h. This file contains typedefs for all functions from the NSDL.</TD></TR></TABLE></DIV></LI>
+ <LI>implement simpleFunction, e.g:
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+etch_int32* simpleFunctionImpl(void* thisx, etch_int32* x){
+ etch_int32* result;
+ result = new_int32(x->value + 1);
+ etch_object_destroy(x);
+ <SPAN class="code-keyword">return</SPAN> result;
+}
+</PRE>
+</DIV></DIV>
+
+<DIV class="panelMacro">
+<TABLE class="noteMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD>The first parameter is an instance of the server_impl object. It also contains a reference to the calling client. You can use this for callbacks (if the call is @AsyncReceiver or @Oneway, otherwise you will end up in a deadlock). To do a callback, do the following:
+<DIV class="code panel" style="border-width: 1px; width: 800px"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+ ((tester_server_impl*)thisx)->client->callbackFunctionName(((tester_server_impl*)thisx)->client, ...);
+</PRE>
+</DIV></DIV></TD></TR></TABLE></DIV>
+
+
+<DIV class="panelMacro"><TABLE class="noteMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD>Parameters of functions have to be destroyed by the function implementation using etch_object_destroy.</TD></TR></TABLE></DIV></LI>
+ <LI>find function new_xxx_server_impl, this function is called when a client connects (the client is given as parameter)</LI>
+ <LI>add the function pointer of simpleFunctionImpl to the pserver object in this function. This "registers" the function as the implementation of the call.
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+xxx_server_impl* new_xxx_server_impl(xxx_remote_client* client) {
+ .... <SPAN class="code-comment">// some other code
+</SPAN> pserver->simpleFunction = pserver_base->simpleFunction = simpleFunctionImpl;
+}
+</PRE>
+</DIV></DIV></LI>
+ <LI>Thats it!</LI>
+</UL>
+
+
+<DIV class="panelMacro"><TABLE class="noteMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD>If you want to return a user defined exception (which was defined in the NSDL), then simply return it in your function implementation instead of the usual return value.</TD></TR></TABLE></DIV>
+
+<H2><A name="CBindingTips%26Tricks-Howtocallamethodontheserver%2Fontheclient"></A>How to call a method on the server / on the client</H2>
+
+<P>As above, the instructions below are symmetrical for client and server. Server directed calls are called like this:</P>
+
+<UL>
+ <LI>open xxx_client_main.c</LI>
+ <LI>find main method</LI>
+ <LI>add your call after the starting of the runtime, e.g.</LI>
+</UL>
+
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+ ...<SPAN class="code-comment">//some code
+</SPAN> etch_int32* result;
+ ...<SPAN class="code-comment">//some code
+</SPAN>
+ <SPAN class="code-comment">//start the runtime and connect
+</SPAN> etch_status = tester_helper_remote_server_start_wait(remote, waitupms);
+ ...<SPAN class="code-comment">//some code
+</SPAN>
+ <SPAN class="code-comment">//call the remote function
+</SPAN> result = remote->simpleFunction(remote,new_int32(42));
+ <SPAN class="code-keyword">if</SPAN>(is_etch_exception(result)){
+ wchar_t* extext = NULL;
+ ex = (etch_exception*)result;
+ <SPAN class="code-keyword">if</SPAN>(etch_exception_get_message(ex)){
+ extext = etch_exception_get_message(ex)->v.valw;
+ }
+ ..<SPAN class="code-comment">//<SPAN class="code-keyword">do</SPAN> something with exception message...
+</SPAN> }<SPAN class="code-keyword">else</SPAN>{
+ ..<SPAN class="code-comment">//<SPAN class="code-keyword">do</SPAN> something with result
+</SPAN> }
+
+ ..<SPAN class="code-comment">//<SPAN class="code-keyword">do</SPAN> something with result
+</SPAN> etch_object_destroy(result);
+}
+</PRE>
+</DIV></DIV>
+<DIV class="panelMacro"><TABLE class="noteMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD>Result Objects have to be freed by the caller using etch_object_destroy. Parameters of calls will be freed by the runtime automatically.</TD></TR></TABLE></DIV>
+
+<DIV class="panelMacro"><TABLE class="noteMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD>You can get an built-in exception from any remote Etch call (e.g. in case of timeouts). This is why the code above contains is_etch_exception(result). <BR>
+Please note that there are special is_blabla_exception test methods generated for used defined exception, which you can use to further refine the type of exception "thrown".</TD></TR></TABLE></DIV>
+
+<H2><A name="CBindingTips%26Tricks-MemoryManagement"></A>Memory Management</H2>
+
+<P>The C Binding for Etch has the following memory management rules:</P>
+<UL>
+ <LI>Implementation side: Parameters of functions have to be destroyed by the function implementation using etch_object_destroy.</LI>
+ <LI>Caller side: Result Objects have to be freed by the caller using etch_object_destroy. Parameters of calls will be freed by the runtime automatically.</LI>
+</UL>
+
+
+<P>All Etch Objects (including the primitive type wrappers) are freed using</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+etch_object_destroy(void* val)
+</PRE>
+</DIV></DIV>
+
+<H2><A name="CBindingTips%26Tricks-Etchprimitivedatatypes"></A>Etch primitive data types</H2>
+
+<P>All primitive types have constructurs of the form </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+new_int32(42)
+</PRE>
+</DIV></DIV>
+
+<H2><A name="CBindingTips%26Tricks-Userdefinedstructtypes"></A>User defined struct types</H2>
+
+<P>Etch generates structs and constructors for user defined types. <BR>
+Assume you have the following in your IDL:</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+ struct simpleStruct (
+ <SPAN class="code-object">int</SPAN> x,
+ <SPAN class="code-object">int</SPAN> y
+ )
+</PRE>
+</DIV></DIV>
+
+<P>The compiler will generate (in xxx_interface.c/.h)</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+typedef struct tester_simpleStruct
+{
+ etch_object object;
+ <SPAN class="code-object">int</SPAN> x;
+ <SPAN class="code-object">int</SPAN> y;
+ } tester_simpleStruct;
+
+
+tester_simpleStruct* new_tester_simpleStruct();
+</PRE>
+</DIV></DIV>
+
+<P>You can pass those structs to Etch function calls just like primitive type wrappers. You can also use etch_object_destroy on them to free the memory.</P>
+
+<H2><A name="CBindingTips%26Tricks-Arraytypes"></A>Array types</H2>
+
+<P>Arrays in the IDL are implemented using the struct</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+etch_nativearray
+</PRE>
+</DIV></DIV>
+
+<P>You have to supply the correct CLASSID for the content for the C Binding to work properly. Here are samples for primitive and complex arrays:</P>
+
+<H3><A name="CBindingTips%26Tricks-PrimitiveArrays"></A>Primitive Arrays</H3>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+ <SPAN class="code-object">int</SPAN> values[4] = {0,1,2,3};
+ <SPAN class="code-keyword">const</SPAN> <SPAN class="code-object">int</SPAN> numdims = 1, itemsize = sizeof(<SPAN class="code-object">int</SPAN>), itemcount = sizeof(values)/itemsize;
+ param = new_etch_nativearray_from (values, CLASSID_ARRAY_INT32,
+ itemsize, numdims, itemcount, 0, 0);
+</PRE>
+</DIV></DIV>
+
+<P>"numdims" is the number of dimensions of the array (e.g. int[] vs. int[][]). The last three parameters of new_etch_nativearray are the sizes of the (up to) three dimensions of the array. More dimensions are not supported. </P>
+
+<H3><A name="CBindingTips%26Tricks-ComplextypedArrays"></A>Complex typed Arrays</H3>
+
+<P>Assume the NSDL with "simpleStruct" from above. Create an array of simplestruct using: </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+ <SPAN class="code-object">int</SPAN> arraysize = 5;
+ tester_simpleStruct** values = etch_malloc(arraysize * sizeof(tester_simpleStruct*),0);
+ ... <SPAN class="code-comment">//fill values
+</SPAN> etch_nativearray* natarray = new_etch_nativearray_from(
+values, CLASSID_ARRAY_STRUCT, sizeof(tester_simpleStruct*), 1, arraysize, 0, 0);
+ natarray->content_class_id = CLASSID_XXX_SIMPLESTRUCT;
+ natarray->content_obj_type = ETCHTYPEB_USER;
+ natarray->is_content_owned = TRUE;
+ ... <SPAN class="code-comment">// <SPAN class="code-keyword">do</SPAN> something with natarray</SPAN>
+</PRE>
+</DIV></DIV>
+
+<DIV class="panelMacro"><TABLE class="noteMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD>For complex typed arrays you have to supply the CLASSID of the content of the object. Those CLASSIDs are generated by the compiler for your user defined types.</TD></TR></TABLE></DIV>
+
+<DIV class="panelMacro"><TABLE class="noteMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD>The field is_content_owned tells Etch whether it should destroy the array content on array destruction, too. This will take effect when calling etch_object_destroy on the natarray or if it is destroyed by the runtime itself (e.g. when it is used as a remote call parameter, see above).</TD></TR></TABLE></DIV>
+ </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>
+ -->
+</TD>
+</TR>
+</TABLE>
+ </BODY>
+</HTML>
Added: websites/staging/etch/trunk/content/etch/documentation/compiler-users-guide.html
==============================================================================
--- websites/staging/etch/trunk/content/etch/documentation/compiler-users-guide.html (added)
+++ websites/staging/etch/trunk/content/etch/documentation/compiler-users-guide.html Thu Dec 15 14:36:04 2011
@@ -0,0 +1,374 @@
+
+<!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>Compiler 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><DIV class="navmenu" style="float:right; background:white; margin:3px; padding:3px"><STYLE type="text/css">/*<![CDATA[*/
+div.rbtoc1249351875454 {margin-left: 0px;padding: 0px;}
+div.rbtoc1249351875454 ul {list-style: none;margin-left: 0px;}
+div.rbtoc1249351875454 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</STYLE><DIV class="rbtoc1249351875454">
+<UL>
+ <LI><SPAN class="TOCOutline">1</SPAN> <A href="#CompilerUsersGuide-EtchCompilerUsersGuide">Etch Compiler Users Guide</A></LI>
+<UL>
+ <LI><SPAN class="TOCOutline">1.1</SPAN> <A href="#CompilerUsersGuide-Name">Name</A></LI>
+ <LI><SPAN class="TOCOutline">1.2</SPAN> <A href="#CompilerUsersGuide-Synopsis">Synopsis</A></LI>
+ <LI><SPAN class="TOCOutline">1.3</SPAN> <A href="#CompilerUsersGuide-Description">Description</A></LI>
+ <LI><SPAN class="TOCOutline">1.4</SPAN> <A href="#CompilerUsersGuide-Options">Options</A></LI>
+ <LI><SPAN class="TOCOutline">1.5</SPAN> <A href="#CompilerUsersGuide-DetailedExamples">Detailed Examples</A></LI>
+</UL>
+</UL></DIV></DIV>
+
+<H1><A name="CompilerUsersGuide-EtchCompilerUsersGuide"></A>Etch Compiler Users Guide</H1>
+<H2><A name="CompilerUsersGuide-Name"></A>Name</H2>
+
+<P>etch - compiler for binding code into the Etch runtime environment.</P>
+
+<H2><A name="CompilerUsersGuide-Synopsis"></A>Synopsis</H2>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>etch --help|-h
+etch --version|-v
+etch [ --output-dir|-d <outputDir> ]
+ [ --who|--what|-w <what> ]
+ [ --ignore-global|-g ] [ --ignore-local|-l ]
+ [ --word-list|-W <wordList> ]
+ [ --include-Path|-I <includePath> ]
+ [ --ignore-Include-Path|-i ]
+ [ --dir-mixin|-m <mixinOutputDir> ]
+ [ --no-mixin-artifacts|-n] [ --no-flatten|-f ] [ --quiet|-q ]
+ --binding|-b <binding> <file>
+</PRE>
+</DIV></DIV>
+
+<H2><A name="CompilerUsersGuide-Description"></A>Description</H2>
+
+<P>The Etch compiler processes input etch files and generates target server and/or client code for the selected binding that is integrated with the Etch runtime environment.</P>
+
+<P>Source and target filename suffixes identify language bindings and the kind of processing performed:</P>
+
+<P>.c C target</P>
+
+<P>.cs C# target</P>
+
+<P>.etch Etch source</P>
+
+<P>.java Java target</P>
+
+<P>.kwd Reserved words lists</P>
+
+<P>.rb Ruby target</P>
+
+<P>.xml XML target</P>
+
+<P>.py Python Target</P>
+
+<H2><A name="CompilerUsersGuide-Options"></A>Options</H2>
+
+<P>This section describes the compiler options in details</P>
+
+<H3><A name="CompilerUsersGuide-HelpOption"></A>Help Option</H3>
+
+<P>--help</P>
+
+<P>-help</P>
+
+<P>-h</P>
+
+<P>?</P>
+
+<P>Print a description of the command options and parameters and then exit.</P>
+
+<H4><A name="CompilerUsersGuide-Usage"></A>Usage</H4>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>etch -h
+</PRE>
+</DIV></DIV>
+
+<H3><A name="CompilerUsersGuide-OutputDirectoryOption"></A>Output Directory Option</H3>
+
+<P>-d outputDir</P>
+
+<P>--outputDir outputDir</P>
+
+<P>Specifies the output directory where etch files will be generated</P>
+
+<H4><A name="CompilerUsersGuide-Usage"></A>Usage</H4>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>etch -d c:\temp Foo.etch
+</PRE>
+</DIV></DIV>
+
+<H3><A name="CompilerUsersGuide-BindingOption"></A>Binding Option</H3>
+
+<P>-b binding</P>
+
+<P>--binding binding</P>
+
+<P>Specifies the target language binding to generate. For example "etch -b java" will generate the java binding. Bindings currently supported are java, csharp and xml. In future the plan is to support c, ruby, python and javascript.</P>
+
+
+
+<H4><A name="CompilerUsersGuide-Usage"></A>Usage</H4>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>etch -b java Foo.etch
+</PRE>
+</DIV></DIV>
+
+<H3><A name="CompilerUsersGuide-Whatoption"></A>What option</H3>
+
+<P>-w what</P>
+
+<P>--who what</P>
+
+<P>--what what</P>
+
+<P>Selects what to generate. What can include: server, client, or both; impl, helper, main, or all; and force.</P>
+
+<P>It is also possible to specify more than one option. For example, a user can specify "etch -w both,helper,main" or "etch -w all". If more than one option is specified, please make sure to separate it by a comma. </P>
+
+<P>Force forces potentially modified files such as impl, main to be overwritten if they already exist in the output directory.</P>
+
+<H4><A name="CompilerUsersGuide-Usage"></A>Usage </H4>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>
+etch -b java -w client Foo.etch
+
+// Generates Client Code
+
+etch -b java -w server Foo.etch
+
+// Generates Server Code
+
+etch -b java -w both Foo.etch
+
+// Generates both client and server code
+
+etch -b java -w both,impl,main Foo.etch
+
+// Generates Impl and Main code for both server and client
+
+etch -b java -w all Foo.etch
+
+// Generates all code Foo.etch (all is a superset of all -w options)
+
+etch -b java -w all,force Foo.etch
+
+// Generates all code, as well as overwrite impl and main for both server and client
+
+</PRE>
+</DIV></DIV>
+
+<H3><A name="CompilerUsersGuide-IgnoreGlobalReservedWordListOption"></A>Ignore Global Reserved Word List Option</H3>
+
+<P>-g</P>
+
+<P>--ignore-global</P>
+
+<P>Ignore the global reserved words list for Etch.</P>
+
+<H3><A name="CompilerUsersGuide-IgnoreLocalReservedWordListOption"></A>Ignore Local Reserved Word List Option</H3>
+
+<P>-l</P>
+
+<P>--ignore-local</P>
+
+<P>Ignore the local reserved words list for the binding.</P>
+
+<H3><A name="CompilerUsersGuide-LoadReservedWordListOption"></A>Load Reserved Word List Option</H3>
+
+<P>-W wordList</P>
+
+<P>--word-list wordList</P>
+
+<P>Specifies the file name of a reserved words list to load, either augmenting or replacing the global and local word lists.</P>
+
+<H3><A name="CompilerUsersGuide-IncludeOption"></A>Include Option</H3>
+
+<P>-I path</P>
+
+<P>--include-path path</P>
+
+<P>Append the specified path to the path of directories searched for include files as defined in the environment variable ETCH_INCLUDE_PATH.</P>
+
+<H4><A name="CompilerUsersGuide-Usage"></A>Usage</H4>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>etch -b java -I c:\temp Foo.etch
+
+Please see Detailed Example section for an elaborate example
+
+</PRE>
+</DIV></DIV>
+
+<H3><A name="CompilerUsersGuide-IgnoreIncludePathOption"></A>Ignore Include Path Option</H3>
+
+<P>-i</P>
+
+<P>--ignore-include-path</P>
+
+<P>Ignore the path of directories searched for include files as defined in the environment variable ETCH_INCLUDE_PATH.</P>
+
+<H3><A name="CompilerUsersGuide-SuppressMixinArtifactOption"></A>Suppress Mixin Artifact Option</H3>
+
+<P>-n</P>
+
+<P>--no-mixin-artifacts</P>
+
+<P>Mixin artifacts are not generated when this option is specified. By default, mixin artifacts will be generated.</P>
+
+<H3><A name="CompilerUsersGuide-MixinDirectoryOption"></A>Mixin Directory Option</H3>
+
+<P>-m outputMixinDir</P>
+
+<P>--dir-Mixin</P>
+
+<P>Directory where mixins will be generated. If -m option is not specified, then mixin will be generated in directory specified by -d option. If etch file contains mixin and neither -m -d and -n are specified, then compiler will throw an error</P>
+
+<H4><A name="CompilerUsersGuide-Usage"></A>Usage</H4>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>etch -b java -m c:\temp\mixin -d c:\temp -w all Foo.etch
+Please see Detailed Example section for an elaborate example
+</PRE>
+</DIV></DIV>
+
+<H3><A name="CompilerUsersGuide-NoFlattenOption%28C%23specific%29"></A>No Flatten Option (C# specific)</H3>
+
+<P>-f<BR>
+--no-flatten</P>
+
+<P>Don't flatten the package directories, but rather nest them like java requires. This option is only for C# binding</P>
+
+<H3><A name="CompilerUsersGuide-RegulateCompilerLogsOption"></A>Regulate Compiler Logs Option</H3>
+
+<P>-q</P>
+
+<P>--quiet</P>
+
+<P>This option suppresses info messages in the compiler. It only report problems.</P>
+
+
+<H3><A name="CompilerUsersGuide-EtchVersion"></A>Etch Version</H3>
+
+<P>-v </P>
+
+<P>--version</P>
+
+<P>Shows the version and exits.</P>
+
+<H2><A name="CompilerUsersGuide-DetailedExamples"></A>Detailed Examples</H2>
+
+
+<H3><A name="CompilerUsersGuide-IncludeExample"></A>Include Example</H3>
+
+<P>To use include files in an etch file, use the .txt extention, not .etch for includes.<BR>
+You can also include other include files in the etch include files.</P>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>module etch.bindings.java.compiler.test
+
+@Direction(Both)
+@Timeout(4000)
+service TestInclude
+{
+ const int INT1 = 98765431;
+
+ const boolean BOOL3 = false
+ const boolean BOOL4 = true
+
+ include "testincl.txt";
+
+ const boolean BOOL1 = false
+ const boolean BOOL2 = true
+
+}
+</PRE>
+</DIV></DIV>
+
+<H4><A name="CompilerUsersGuide-testincl.txt"></A>testincl.txt</H4>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>
+const int INT2 = -2147483648;
+include "testincl1.txt";
+</PRE>
+</DIV></DIV>
+
+<H3><A name="CompilerUsersGuide-MixinExample"></A>Mixin Example</H3></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: websites/staging/etch/trunk/content/etch/documentation/csharp-binding-users-guide.html
==============================================================================
--- websites/staging/etch/trunk/content/etch/documentation/csharp-binding-users-guide.html (added)
+++ websites/staging/etch/trunk/content/etch/documentation/csharp-binding-users-guide.html Thu Dec 15 14:36:04 2011
@@ -0,0 +1,551 @@
+
+<!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>Csharp Binding 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><H1><A name="CsharpBindingUsersGuide-Introduction"></A>Introduction</H1>
+
+<P>This document will provide details on how to build an etch application using csharp.</P>
+
+<H1><A name="CsharpBindingUsersGuide-SampleEtchFile"></A>Sample Etch File</H1>
+
+<P>The following is the etch file we will refer to in this document. Lets call this File Example.etch and store it in directory c:\EtchExamples\Example</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>module etch.examples.example
+
+/**
+ * Service version of hello world.
+ */
+service Example
+{
+
+ /** the number of times to perform the action */
+ const int COUNT = 4
+
+ /* Exception thrown if ping doesn't work.
+ * @param msg the explanation.
+ */
+ exception PongException ( string msg )
+
+
+ /**
+ * Says hello to the server.
+ * @param msg a greeting for the server.
+ * @param d the current date.
+ * @return the id of our hello
+ */
+ @Timeout( 1234 )
+ @Direction( Server )
+ int helloServer( string msg, Datetime d )
+
+ /**
+ * Says hello to the client.
+ * @param msg a greeting for the client.
+ * @return the id of our hello
+ */
+ @Timeout( 2345 )
+ @Direction( Client )
+ int helloClient( string msg )
+
+ /**
+ * Says hello to the client or server.
+ * @param msg a greeting for the client or server.
+ * @return the id of our hello
+ */
+ @Timeout( 3456 )
+ @Direction( Both )
+ int hello( string msg )
+
+ /**
+ * Says howdy to the server. Oneway.
+ * @param msg a greeting for the server.
+ */
+ @Oneway
+ @Direction( Server )
+ void howdyServer( string msg )
+
+ /**
+ * Says howdy to the client. Oneway.
+ * @param msg a greeting for the client.
+ */
+ @Oneway
+ @Direction( Client )
+ void howdyClient( string msg )
+
+ /**
+ * Says howdy to the client or server. Oneway.
+ * @param msg a greeting for the client or server.
+ */
+ @Oneway
+ @Direction( Both )
+ void howdy( string msg )
+
+ /**
+ * Pings the other side.
+ * @throws PongException
+ */
+ @Timeout( 4567 )
+ @Direction( Both )
+ @AsyncReceiver( Queued )
+ void ping() throws PongException
+}
+</PRE>
+</DIV></DIV>
+
+<H1><A name="CsharpBindingUsersGuide-UsingEtchCompiler"></A>Using Etch Compiler</H1>
+
+<P>Before compiling etch file, please make sure Etch is installed and is present in the path</P>
+
+<H2><A name="CsharpBindingUsersGuide-CommandLine"></A>Command Line</H2>
+
+<UL>
+ <LI>Before we generate the server code, lets create a directory for server (c:\EtchExamples\Example\server).</LI>
+</UL>
+
+
+<UL>
+ <LI>From the command line, use the following command to generate the server side code</LI>
+</UL>
+
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>etch -b csharp -d .\server -w server,impl,main Example.etch
+</PRE>
+</DIV></DIV>
+
+<UL>
+ <LI>This command will generate the server side code under</LI>
+</UL>
+
+
+<P>c:\EtchExamples\Example\server\etch.examples.example</P>
+
+<UL>
+ <LI>The directory name "etch.examples.example" is generated by the compiler. This name corresponds to the module name of the etch file.</LI>
+</UL>
+
+
+<UL>
+ <LI>Like we did for server, lets create a directory for client (c:\EtchExamples\Example\client)</LI>
+</UL>
+
+
+<UL>
+ <LI>Similarly using the following command to generate the client side code
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>etch -b csharp -d .\client -w client,impl,main Example.etch
+</PRE>
+</DIV></DIV></LI>
+</UL>
+
+
+<UL>
+ <LI>This command will generate the client code under</LI>
+</UL>
+
+
+<P>c:\EtchExamples\Example\client\etch.examples.example</P>
+
+<P>Please refer to the Etch Compiler Guide for more details on the various compiler options</P>
+
+<H2><A name="CsharpBindingUsersGuide-VisualStudioPlugin"></A>Visual Studio Plugin</H2>
+
+<UL>
+ <LI>If you are using Visual Studio as your IDE, then you can install the Visual Studio Etch Plugin. TODO Make sure the setup.exe for the plugin is a part of etch install...</LI>
+</UL>
+
+
+<UL>
+ <LI>Once the plugin has been installed, open Visual Studio and goto Tools->Add-in Manager. Make sure Etch is checked</LI>
+</UL>
+
+
+<UL>
+ <LI>Create a new Empty solution add two projects client and server to the solution.</LI>
+</UL>
+
+
+<UL>
+ <LI>Copy Example.etch to both client and server project</LI>
+</UL>
+
+
+<UL>
+ <LI>Right click on the etch file in the solution explorer and chose server compiler option for server project. Add the generated files to the project by right clicking on the project and choosing Add->Existing Item. Do the exact same thing for client project</LI>
+</UL>
+
+
+
+<H1><A name="CsharpBindingUsersGuide-GeneratedFiles"></A>Generated Files</H1>
+
+<P>Once the etch file has been compiled successfully, either from command line or Visual Studio Plugin, a bunch of files are generated.</P>
+
+<P>This section briefly explains the purpose of each generated file.</P>
+
+<H3><A name="CsharpBindingUsersGuide-InterfaceFiles"></A>Interface Files</H3>
+
+<P>Example.cs<BR>
+ExampleClient.cs<BR>
+ExampleServer.cs</P>
+
+<P>These three files are the generated interface classes. Service defined constants and types are in Example.cs, as well as direction "both" messages, which are messages which are shared between client and server. ExampleClient.cs and ExampleServer.cs are respectively the messages for just the direction client or server. These Files should not be edited by the user</P>
+
+<H3><A name="CsharpBindingUsersGuide-RemoteFiles"></A>Remote Files</H3>
+
+<P>RemoteExample.cs<BR>
+RemoteExampleClient.cs<BR>
+RemoteExampleServer.cs</P>
+
+<P>RemoteExample*.cs are the generated classes which implement the interfaces, with message implementations which encode the message type and arguments for transport to the connection peer and then receive and decode any response. These files should not be edited by the user either</P>
+
+<H3><A name="CsharpBindingUsersGuide-StubFiles"></A>Stub Files</H3>
+
+<P>StubExample.cs<BR>
+StubExampleServer.cs<BR>
+StubExampleClient.cs</P>
+
+<P>StubExample*.cs are the generated classes which receive messages encoded by RemoteExample*.cs and decode them, calling the appropriate message implementation and then encoding and sending any result. These Files are also not edited by the user</P>
+
+<H3><A name="CsharpBindingUsersGuide-ValueFactoryFile"></A>Value Factory File</H3>
+
+<P>ValueFactoryExample.cs</P>
+
+<P>ValueFactoryExample.cs is a generated class which contains helper code to serialize service defined types and also the meta data which describes the messages and fields, field types, timeouts, etc. This file is also not edited by the user</P>
+
+<H3><A name="CsharpBindingUsersGuide-BaseFiles"></A>Base Files</H3>
+
+<P>BaseExample.cs<BR>
+BaseExampleClient.cs<BR>
+BaseExampleServer.cs</P>
+
+<P>BaseExample*.cs are generated classes which implement the interfaces, with message implementations which call the delegate. If no delegate is defined i.e. if delegate is null, an UnsupportedOperationException is thrown. These files are also not edited by the user</P>
+
+<H3><A name="CsharpBindingUsersGuide-ImplFiles"></A>Impl Files</H3>
+
+<P>ImplExampleClient.cs<BR>
+ImplExampleServer.cs</P>
+
+<P>ImplExample*.cs are the generated sample client and server implementation classes. They extend the generated base classes. These are used by the sample main programs to provide implementations of the client or server messages. Edit these files as you wish to implement your service (overriding the default implementations from the generated base classes or uisng delegates).</P>
+
+<H3><A name="CsharpBindingUsersGuide-HelperFile"></A>Helper File</H3>
+
+<P>ExampleHelper.cs</P>
+
+<P>ExampleHelper.cs is a generated class which includes static methods to help construct transports for client and listener. This file should not be edited by the user</P>
+
+<H3><A name="CsharpBindingUsersGuide-MainFiles"></A>Main Files</H3>
+
+<P>MainExampleClient.cs<BR>
+MainExampleListener.cs</P>
+
+<P>MainExample*.cs are the generated sample client and server main programs. They show how to setup a transport and start it and how to create a session. Edit these files as you wish to implement your service, or just copy the code into your own application.</P>
+
+<H1><A name="CsharpBindingUsersGuide-ChangesRequiredtoMaketheApplicationWork"></A>Changes Required to Make the Application Work</H1>
+
+<P>Only a few files need to be edited to make the etch application run.</P>
+
+<H2><A name="CsharpBindingUsersGuide-MainExampleListener"></A>MainExampleListener</H2>
+
+<P>As mentioned in the previous section, MainExampleListener is the class where the listener (server) is started. The user needs to edit the URI to point to the location where listener must listen for connection from the client</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>string uri = "tcp://localhost:4002";
+</PRE>
+</DIV></DIV>
+<P>In the above code snippet, the listener will run at port 4002 on localhost.</P>
+
+<P>When the listener accepts a connection from the client, an server object (ImplExampleServer) is created to service the client request. The code to create the Impl object is auto generated by the compiler.</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>public ExampleServer NewExampleServer( RemoteExampleClient client )
+{
+ return new ImplExampleServer( client );
+}
+</PRE>
+</DIV></DIV>
+<P>If a user wishes to, he can pass more parameters to the Impl Object. In the context of our example, we do not need to pass any other arguments, thus we will keep the generated code as is.</P>
+
+<P>In summary, editing the uri is the only change required for our example.</P>
+
+<H2><A name="CsharpBindingUsersGuide-ImplExampleServer"></A>ImplExampleServer</H2>
+
+<P>In this class, we will provide implementation of any "both" or "server" directed messages. To get a better understanding of what is meant by "both" and "server" directed message, lets look at snippet of Example.etch</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE> @Timeout( 3456 )
+ @Direction( Both )
+ int hello( string msg )
+
+ @Oneway
+ @Direction( Server )
+ void howdyServer( string msg )
+
+ @Oneway
+ @Direction( Client )
+ void howdyClient( string msg )
+
+</PRE>
+</DIV></DIV>
+<P>The keyword @Direction(....) is used to specify the direction of the message. @Direction(server) implies that the message is headed towards the server. Both implies that the message can be directed towards the server or client. For more details please refer to the Etch Language Reference Manual.</P>
+
+<P>For our purpose, in ImplExampleServer we will only implement the messages that are directed towards server "@Direction(Server)" or both "@Direction(Both)"</P>
+
+<P>ImplExampleServer extends from BaseExampleServer which provides a default implementation of all messages with direction server or both. Below is a snippet of BaseExampleServer</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>...
+...
+...
+/// <summary>
+/// Delegate Definition; Please do not modify
+/// </summary>
+
+public delegate int? _delegate_type_helloServer (string msg, System.DateTime? d);
+
+/// <summary>
+/// Add your implementation method to this variable
+/// </summary>
+
+public _delegate_type_helloServer _delegate_helloServer;
+
+
+public virtual int? helloServer (string msg, System.DateTime? d)
+{
+
+ if (_delegate_helloServer != null)
+ return _delegate_helloServer(msg,d);
+ else
+ throw new NotSupportedException( "helloServer" );
+}
+...
+...
+...
+</PRE>
+</DIV></DIV>
+<P>In ImplExampleServer we can either override method helloServer or use the power of delegate (see example below for how to use delegate)</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>public ImplExampleServer(RemoteExampleClient client)
+{
+ this.client = client;
+ _delegate_helloServer = SayHello;
+}
+
+/// <summary>A connection to the client session. Use this to
+/// send a message to the client.</summary>
+private readonly RemoteExampleClient client;
+
+public int? SayHello(string msg, DateTime? d)
+{
+ Console.WriteLine("Msg is {0} and date is {1}", msg,d);
+ return 0;
+}
+
+</PRE>
+</DIV></DIV>
+<P>Notice that method SayHello is assigned to delegate _delegate_helloServer in the constructor.</P>
+
+<P>In summary, ImplExampleServer is where the actual server implementation resides. The user can choose to either override the methods in BaseExampleServer or assign methods to delegates.</P>
+
+<H2><A name="CsharpBindingUsersGuide-MainExampleClient"></A>MainExampleClient</H2>
+
+<P>The uri in MainExampleClient needs to be modified such that it points to location where listener was started. In the context of our example the uri will point to the following</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>string uri = "tcp://localhost:4002";
+</PRE>
+</DIV></DIV>
+<P>The compiler generates code to setup up the transport layer. It also gets an instance of RemoteExampleServer. The client uses RemoteExampleServer to send messages to server.<BR>
+In the context of our example, we will call method helloServer on RemoteExampleServer. Following is a code snippet</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>public static void Main(String[] args)
+{
+
+ string uri = "tcp://localhost:4002";
+
+ RemoteExampleServer server = ExampleHelper.NewServer( uri, null, new MainExampleClient());
+
+ // Connect to the service
+ server._StartAndWaitUp( 4000 );
+
+ server.helloServer("Hi !!!", DateTime.Now);
+
+ // Disconnect from the service
+ server._StopAndWaitDown( 4000 );
+
+}
+
+</PRE>
+</DIV></DIV>
+<P>Thus a user only needs to change the uri and use the RemoteExampleServer instance to invoke messages on the server</P>
+
+<H2><A name="CsharpBindingUsersGuide-ImplExampleClient"></A>ImplExampleClient</H2>
+
+<P>MainExampleClient also contains method NewExampleClient, which creates an ImplExampleClient object. This class provides implementation of "both" directed and "client" directed messages. This class is analogous to the ImplExampleServer. The only difference being that ImplExampleServer implemented "server" and "both" directed messages, while ImplExampleClient implements "client" and "both" directed messages.</P>
+
+<P>To see ImplExampleClient at work, we will have to modify ImlExampleServer as well. In ImplExampleServer section, we provided implementation of helloServer method using delegates, lets tweak this a little such that the server replies back client with a howdyClient message.</P>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>public ImplExampleServer(RemoteExampleClient client)
+{
+ this.client = client;
+ _delegate_helloServer = SayHello;
+}
+
+/// <summary>A connection to the client session. Use this to
+/// send a message to the client.</summary>
+private readonly RemoteExampleClient client;
+
+public override int? helloServer(string msg, DateTime? d)
+{
+ Console.WriteLine("Msg is {0} and date is {1} ", msg, d);
+ client.howdyClient("Hi Client");
+ return 0;
+}
+</PRE>
+</DIV></DIV>
+
+<P>It is very important to remember that howdyClient is defined as a @oneway message in the Example etch file. Such messages don't wait for a response. They are often referred to as event or "fire and forget" message. If howdyClient was not defined as @oneway, it would have resulted in a deadlock or a timeout exception. This is because client would expect to hear back from helloServer message, while server would be waiting to hear back from howdyClient. Since neither can respond until they hear from the other, they will eventually timeout if a timeout has been defined or just wait indefinitely. However since howdyClient message has been defined as @oneway the server does not have to wait for a response from the client.</P>
+
+<P>In summary, ImplExampleClient is the place where the client implementation resides. The user can chose to override the base implementation provided in BaseExampleClient or assign methods to delegates.</P>
+
+<H1><A name="CsharpBindingUsersGuide-CompileandRuntheApplication"></A>Compile and Run the Application</H1>
+
+<H2><A name="CsharpBindingUsersGuide-UsingCSC"></A>Using CSC</H2>
+
+<P>Please make sure that .NET 2.0 or greater is installed on your system</P>
+
+<P>Building on our example, lets first compile the server files. </P>
+
+<UL>
+ <LI>The first step would be to change directory to the server location<BR>
+(c:\EtchExamples\Example\server\etch.examples.example). </LI>
+</UL>
+
+
+<UL>
+ <LI>The next step would be to copy Etch.dll from Etch Home Directory to the server directory.</LI>
+</UL>
+
+
+<UL>
+ <LI>Once the file is copied, use csc to compile the *.cs file.</LI>
+</UL>
+
+
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>
+copy "%ETCH_HOME%\lib\Etch.dll" .
+
+csc "/reference:%ETCH_HOME%\lib\Etch.dll" /main:etch.examples.example.MainExampleListener *.cs
+
+</PRE>
+</DIV></DIV>
+
+<P>If there are no compile errors MainExampleListener.exe is created. Use the exe file to run the listener.</P>
+
+<P>For the client files, cd to the client directory and follow the same instructions as mentioned above. In csc command replace etch.examples.example.MainExampleListener with<BR>
+etch.examples.example.MainExampleClient</P>
+
+<P>use MainExampleClient.exe to run the client.</P>
+
+<H2><A name="CsharpBindingUsersGuide-UsingVisualStudio"></A>Using Visual Studio</H2>
+
+<UL>
+ <LI>Please make sure you have followed the steps mentioned in section "Visual Studio Plugin".</LI>
+</UL>
+
+
+<UL>
+ <LI>Add %ETCH_HOME%\lib\Etch.dll as a reference to both client and server project</LI>
+</UL>
+
+
+<UL>
+ <LI>Build solution by either right clicking on solution and choosing Rebuild Solution or by using keyborad shortcut (CTRL+SHIFT+B).</LI>
+</UL>
+
+
+<P>To Run the Application</P>
+
+<UL>
+ <LI>Right click on the server project and chose "Set as Startup Project".</LI>
+</UL>
+
+
+<UL>
+ <LI>Press CTRL+F5 to run the listener or server.</LI>
+</UL>
+
+
+<UL>
+ <LI>Follow the above two steps to run client as well.</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: websites/staging/etch/trunk/content/etch/documentation/documentation.html
==============================================================================
--- websites/staging/etch/trunk/content/etch/documentation/documentation.html (added)
+++ websites/staging/etch/trunk/content/etch/documentation/documentation.html Thu Dec 15 14:36:04 2011
@@ -0,0 +1,96 @@
+
+<!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>Documentation</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 style="border:0px"><TR>
+ <TD class="" valign="top" width="90%">
+ <P><H4><A name="Documentation-GettingStarted"></A>Getting Started</H4>
+ <A href="overview.html" title="Overview">Overview</A> - What is Etch and why should I care<BR>
+ <A href="architecture.html" title="Architecture">Architecture</A> - Architecture summary<BR>
+ <A href="setup-guide-for-users.html" title="Setup Guide for Users">User Setup Guide</A> - installing Etch and using it<BR>
+ <A href="examples.html" title="Examples">Examples</A> - example applications and services using Etch<BR>
+ </P>
+
+
+ <H4><A name="Documentation-Reference"></A>Reference</H4>
+
+ <P><A href="language-reference.html" title="Language Reference">Language Reference</A> - Etch IDL reference<BR>
+ <A href="etch-binary-protocol.html" title="Etch Binary Protocol">Etch Binary Protocol</A> - Etch serialization format <BR>
+ <A href="compiler-users-guide.html" title="Compiler Users Guide">Compiler Users Guide</A> - Etch compiler command-line options<BR>
+ <A href="generated-code-users-guide.html" title="Generated Code Users Guide">Generated Code Users Guide</A> - Navigating generated code</P>
+
+ <H4><A name="Documentation-AdvancedTopics"></A>Advanced Topics</H4>
+
+ <P><A href="howto-tls.html" title="Howto - TLS">TLS</A> - Using TLS with Etch<BR>
+ <A href="howto-keepalive-filter.html" title="Howto - KeepAlive Filter">KeepAlive Filter</A> - Setting up keep-alive's for connections<BR>
+ <A href="howto-pwauth-filter.html" title="Howto - Pwauth Filter">Pwauth Filter</A> - Setting up connection authorizations<BR>
+ <A href="howto-logger-filter.html" title="Howto - Logger Filter">Logger Filter</A> - Setting up logging<BR>
+
+ </TR>
+ </TABLE>
+ </DIV>
+ </DIV>
+ </DIV>
+ <!--
+ <div class="footer">
+ Generated by
+ <a href="http://www.atlassian.com/confluence/">Atlassian Confluence</a> (Version: 3.4.9 Build: 2042 Feb 14, 2011)
+ <a href="http://could.it/autoexport/">Auto Export Plugin</a> (Version: 1.0.0- dkulp)
+ </div>
+ -->
+ </BODY>
+</HTML>
Added: websites/staging/etch/trunk/content/etch/documentation/etch-binary-protocol.html
==============================================================================
--- websites/staging/etch/trunk/content/etch/documentation/etch-binary-protocol.html (added)
+++ websites/staging/etch/trunk/content/etch/documentation/etch-binary-protocol.html Thu Dec 15 14:36:04 2011
@@ -0,0 +1,226 @@
+
+<!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>Etch Binary Protocol</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="EtchBinaryProtocol-ExampleNSDL"></A>Example NSDL</H2>
+
+<P>The Etch binary protocol is illustrated using the following example NSDL:</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+module org.apache.etch.example.binary
+
+service binaryExample {
+ struct A ( <SPAN class="code-object">int</SPAN> c )
+ <SPAN class="code-object">int</SPAN> f(A[] as)
+}
+</PRE>
+</DIV></DIV>
+
+<H2><A name="EtchBinaryProtocol-HashedValues"></A>Hashed Values</H2>
+
+<P>Etch uses hashed values to identify names (such as names of parameters or functions). The values are computed by hashing the full qualified names of the elements. As an example, the computed hash values for the example above are:</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+org.apache.etch.example.binary.binaryExample.f = 0x28e34aa1
+org.apache.etch.example.binary.binaryExample._result_f = 0x0972201e
+org.apache.etch.example.binary.binaryExample.A = 0x28e34a7c
+c = 0x150a2c9e
+as = 0x5a1cfad7
+_messageId = 0x6306b468
+_inReplyTo = 0xeda8c9a6
+</PRE>
+</DIV></DIV>
+
+<H2><A name="EtchBinaryProtocol-ExampleCode"></A>Example Code</H2>
+<P>Consider the following Java program for the NSDL Idl:</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+binaryExample.A a1 = <SPAN class="code-keyword">new</SPAN> binaryExample.A(1);
+binaryExample.A a2 = <SPAN class="code-keyword">new</SPAN> binaryExample.A(2);
+binaryExample.A[] as = {a1, a2};
+<SPAN class="code-object">Integer</SPAN> res = server.f(as);
+</PRE>
+</DIV></DIV>
+
+<H2><A name="EtchBinaryProtocol-RequestMessage%3A"></A>Request Message:</H2>
+<P>The request message for the call server.f(as) in the program above will be:</P>
+
+<DIV class="code panel" style="border-width: 1px; width: 800px"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+0xde,0xad,0xbe,0xef,0x0,0x0,0x0,0x41,0x3,0x86,0x28,0xe3,0x4a,0xa1,0x2,0x86,0x63,0x6,0xb4,0x68,0x87,0x0,0x0,0x1,0x2b,0x1f,0x33,0x1c,0x6b,0x86,0x5a,0x1c,0xfa,0xd7,0x91,0x95,0x86,0x28,0xe3,0x4a,0x7c,0x1,0x2,0x95,0x86,0x28,0xe3,0x4a,0x7c,0x1,0x86,0x15,0xa,0x2c,0x9e,0x1,0x81,0x95,0x86,0x28,0xe3,0x4a,0x7c,0x1,0x86,0x15,0xa,0x2c,0x9e,0x2,0x81,0x81,0x81
+</PRE>
+</DIV></DIV>
+
+<P>Lets explain this in detail:</P>
+
+<DIV class="code panel" style="border-width: 1px; width: 800px"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+ HEADER_______________________________________________________________________________________________
+ 0xde 0xad 0xbe 0xef etch identifier
+ 0x00 0x00 0x00 0x41 etch message length (0x41 bytes)
+ 0x03 etch protocol version
+ CALL of f____________________________________________________________________________________________
+ 0x86 type flag: INT
+ 0x28 0xe3 0x4a 0xa1 INT value: hash <SPAN class="code-keyword">for</SPAN> name of message: Call of F
+ 0x02 size of parameters (1 param <SPAN class="code-keyword">for</SPAN> f + message ID)
+ Message ID___________________________________________________________________________________________
+ 0x86 type flag: INT
+ 0x63 0x06 0xb4 0x68 INT value: hash <SPAN class="code-keyword">for</SPAN> <SPAN class="code-quote">"_messageId"</SPAN>
+ 0x87 type flag LONG
+ 0x0 0x0 0x1 0x2b 0x1f 0x33 0x1c 0x6b LONG value: MessageID (unique <SPAN class="code-keyword">for</SPAN> <SPAN class="code-keyword">this</SPAN> call)
+ param of call (array as)_____________________________________________________________________________
+ 0x86 type flag: INT
+ 0x5a 0x1c 0xfa 0xd7 INT value: hash <SPAN class="code-keyword">for</SPAN> <SPAN class="code-quote">"as"</SPAN>
+ 0x91 type flag: ARRAY
+ type of array_________________________________________________________________________________
+ 0x95 type flag: (type of array elems) CUSTOM
+ 0x86 type flag: INT
+ 0x28 0xe3 0x4a 0x7c INT value: hash <SPAN class="code-keyword">for</SPAN> <SPAN class="code-quote">"A"</SPAN> (<SPAN class="code-keyword">super</SPAN> type of all array elems)
+ 0x01 INT value: dimension of array
+ 0x02 INT value: number of array elements
+ first array element___________________________________________________________________________
+ 0x95 type flag: CUSTOM
+ 0x86 type flag: INT
+ 0x28 0xe3 0x4a 0x7c INT value: hash <SPAN class="code-keyword">for</SPAN> <SPAN class="code-quote">"A"</SPAN> (type of elem)
+ 0x1 INT value: number of fields of A (only one: c)
+ field values of first array element____________________________________________________
+ 0x86 type flag: INT
+ 0x15 0x0a 0x2c 0x9e INT value: hash <SPAN class="code-keyword">for</SPAN> <SPAN class="code-quote">"c"</SPAN> (name of A's field)
+ 0x01 INT value: value of A.c
+ 0x81 NONE value: end delimiter <SPAN class="code-keyword">for</SPAN> struct A
+ second array element__________________________________________________________________________
+ 0x95 type flag: CUSTOM
+ 0x86 type flag: INT
+ 0x28 0xe3 0x4a 0x7c INT value: hash <SPAN class="code-keyword">for</SPAN> <SPAN class="code-quote">"A"</SPAN> (type of elem)
+ 0x1 INT value: number of fields of A (only one: c)
+ field values of second array element____________________________________________________
+ 0x86 type flag: INT
+ 0x15 0xa 0x2c 0x9e INT value: hash <SPAN class="code-keyword">for</SPAN> <SPAN class="code-quote">"c"</SPAN> (name of A's field)
+ 0x2 INT value: value of A.c
+ 0x81 NONE value: end delimiter <SPAN class="code-keyword">for</SPAN> struct A
+ 0x81 NONE value: end delimiter <SPAN class="code-keyword">for</SPAN> param array
+ 0x81 NONE value: end delimiter <SPAN class="code-keyword">for</SPAN> call of f
+</PRE>
+</DIV></DIV>
+
+<H2><A name="EtchBinaryProtocol-ReturnMessage%3A"></A>Return Message:</H2>
+
+<P>The return message will be serialized just like that, but additionally contains a "_inReplyTo" ID. This ID is the _messageID value of the request message. This enables Etch to find the right caller for this response. Of course the message is much simpler, since it only contains a single integer return value, _inReplyTo and _messageID</P>
+
+<H2><A name="EtchBinaryProtocol-Implementation"></A>Implementation</H2>
+
+<P>The <A href="https://svn.apache.org/repos/asf/incubator/etch/trunk/binding-java/runtime/src/main/java/org/apache/etch/bindings/java/transport/fmt/binary/BinaryTaggedDataOutput.java" class="external-link" rel="nofollow">BinaryTaggedDataOutput</A> class implements the serialization in Etch. It's code is pretty good to understand and is - at the moment - the availble specification for the whole protocol. Start with the writeMessage function.</P>
+
+<H2><A name="EtchBinaryProtocol-TypeCodes%3A"></A>Type Codes:</H2>
+
+<P>Here are all current type codes, which Etch uses:</P>
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+ ANY = 0x96
+ CUSTOM = 0x95
+ STRING = 0x93
+ EMPTY_STRING = 0x92
+ ARRAY = 0x91
+ DOUBLES = 0x90
+ BYTES = 0x8b
+ DOUBLE = 0x89
+ FLOAT = 0x88
+ LONG = 0x87
+ INT = 0x86
+ SHORT = 0x85
+ BYTE = 0x84
+ NULL = 0x80
+ NONE = 0x81
+ BOOLEAN_FALSE = 0x82
+ BOOLEAN_TRUE = 0x83
+</PRE>
+</DIV></DIV>
+
+<P>Optimization:<BR>
+Any Integer value between </P>
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+ MAX_TINY_INT = 0x7f = 127
+ MIN_TINY_INT = 0xc0 = -64
+</PRE>
+</DIV></DIV>
+<P>will be serialized directly without specifying an own type flag. Bigger or smaller Integer Values will have their own type flag before the value.</P>
+ </DIV>
+
+
+
+ </DIV>
+ </DIV>
+ <!--
+ <div class="footer">
+ Generated by
+ <a href="http://www.atlassian.com/confluence/">Atlassian Confluence</a> (Version: 3.4.9 Build: 2042 Feb 14, 2011)
+ <a href="http://could.it/autoexport/">Auto Export Plugin</a> (Version: 1.0.0- dkulp)
+ </div>
+ -->
+ </TD>
+</TR>
+</TABLE>
+
+ </BODY>
+</HTML>