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 [3/5] - in /websites/staging/etch/trunk/content/etch: ./
documentation/ documentation/architecture.data/
documentation/howto-logger-filter.data/ documentation/resources/
Added: websites/staging/etch/trunk/content/etch/documentation/language-reference.html
==============================================================================
--- websites/staging/etch/trunk/content/etch/documentation/language-reference.html (added)
+++ websites/staging/etch/trunk/content/etch/documentation/language-reference.html Thu Dec 15 14:36:04 2011
@@ -0,0 +1,1007 @@
+
+<!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>Language Reference</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.rbtoc1250892338373 {margin-left: 0px;padding: 0px;}
+div.rbtoc1250892338373 ul {list-style: none;margin-left: 0px;}
+div.rbtoc1250892338373 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</STYLE><DIV class="rbtoc1250892338373">
+<UL>
+ <LI><SPAN class="TOCOutline">1</SPAN> <A href="#LanguageReference-Introduction">Introduction</A></LI>
+ <LI><SPAN class="TOCOutline">2</SPAN> <A href="#LanguageReference-SyntaxElements">Syntax Elements</A></LI>
+ <LI><SPAN class="TOCOutline">3</SPAN> <A href="#LanguageReference-NativeDataTypes">Native Data Types</A></LI>
+ <LI><SPAN class="TOCOutline">4</SPAN> <A href="#LanguageReference-ExtendedTypes">Extended Types</A></LI>
+<UL>
+ <LI><SPAN class="TOCOutline">4.1</SPAN> <A href="#LanguageReference-Datetime">Datetime</A></LI>
+ <LI><SPAN class="TOCOutline">4.2</SPAN> <A href="#LanguageReference-List">List</A></LI>
+ <LI><SPAN class="TOCOutline">4.3</SPAN> <A href="#LanguageReference-Set">Set</A></LI>
+ <LI><SPAN class="TOCOutline">4.4</SPAN> <A href="#LanguageReference-Map">Map</A></LI>
+</UL>
+ <LI><SPAN class="TOCOutline">5</SPAN> <A href="#LanguageReference-ObjectDataType">Object Data Type</A></LI>
+<UL>
+ <LI><SPAN class="TOCOutline">5.1</SPAN> <A href="#LanguageReference-Constants">Constants</A></LI>
+ <LI><SPAN class="TOCOutline">5.2</SPAN> <A href="#LanguageReference-Enumerations">Enumerations</A></LI>
+ <LI><SPAN class="TOCOutline">5.3</SPAN> <A href="#LanguageReference-StructuredType">Structured Type</A></LI>
+ <LI><SPAN class="TOCOutline">5.4</SPAN> <A href="#LanguageReference-Arrays">Arrays</A></LI>
+ <LI><SPAN class="TOCOutline">5.5</SPAN> <A href="#LanguageReference-ExternalType">External Type</A></LI>
+ <LI><SPAN class="TOCOutline">5.6</SPAN> <A href="#LanguageReference-Exceptions">Exceptions</A></LI>
+ <LI><SPAN class="TOCOutline">5.7</SPAN> <A href="#LanguageReference-Messages">Messages</A></LI>
+ <LI><SPAN class="TOCOutline">5.8</SPAN> <A href="#LanguageReference-Includes">Includes</A></LI>
+ <LI><SPAN class="TOCOutline">5.9</SPAN> <A href="#LanguageReference-Mixin">Mixin</A></LI>
+ <LI><SPAN class="TOCOutline">5.10</SPAN> <A href="#LanguageReference-Service">Service</A></LI>
+ <LI><SPAN class="TOCOutline">5.11</SPAN> <A href="#LanguageReference-Annotations">Annotations</A></LI>
+ <LI><SPAN class="TOCOutline">5.12</SPAN> <A href="#LanguageReference-Module">Module</A></LI>
+</UL>
+ <LI><SPAN class="TOCOutline">6</SPAN> <A href="#LanguageReference-SupportedAnnotations">Supported Annotations</A></LI>
+<UL>
+ <LI><SPAN class="TOCOutline">6.1</SPAN> <A href="#LanguageReference-@AsyncReceiver">@AsyncReceiver</A></LI>
+ <LI><SPAN class="TOCOutline">6.2</SPAN> <A href="#LanguageReference-@Authorize">@Authorize</A></LI>
+ <LI><SPAN class="TOCOutline">6.3</SPAN> <A href="#LanguageReference-@Direction">@Direction</A></LI>
+ <LI><SPAN class="TOCOutline">6.4</SPAN> <A href="#LanguageReference-@Extern">@Extern</A></LI>
+ <LI><SPAN class="TOCOutline">6.5</SPAN> <A href="#LanguageReference-@Oneway">@Oneway</A></LI>
+ <LI><SPAN class="TOCOutline">6.6</SPAN> <A href="#LanguageReference-@Timeout">@Timeout</A></LI>
+ <LI><SPAN class="TOCOutline">6.7</SPAN> <A href="#LanguageReference-@ToString">@ToString</A></LI>
+ <LI><SPAN class="TOCOutline">6.8</SPAN> <A href="#LanguageReference-@Unchecked">@Unchecked</A></LI>
+</UL>
+ <LI><SPAN class="TOCOutline">7</SPAN> <A href="#LanguageReference-FormalComments">Formal Comments</A></LI>
+</UL></DIV></DIV>
+
+<H1><A name="LanguageReference-Introduction"></A>Introduction</H1>
+
+<P>The Network Service Definition Language is used to specify the message exchange between client / server applications. The language specifies the messages, their parameters, message direction, timeout, authorization, delivery style, custom types, constants, and documentation for the service and each message, parameter, type, and constant. A compiler can then be used to process the NSDL into meta-data and code to support implementing clients and servers in a variety of different programming languages and environments with the help of a small runtime library.</P>
+
+<H1><A name="LanguageReference-SyntaxElements"></A>Syntax Elements</H1>
+
+<P>The NSDL uses syntax elements common to other programming languages:</P>
+<UL>
+ <LI>Keywords are used to identify grammar elements such as service, constants, enumerations, structured types, external types, exceptions, and native types. The keywords are: boolean, byte, const, double, enum, exception, extends, extern, false, float, int, long, mixin, include, module, null, object, service, short, string, struct, throws, true, and void. Keywords may not be used as an identifier for any service defined element.</LI>
+ <LI>Boolean, numeric, and string literals are used to specify the values of constants, and as arguments to annotations. Examples include true, 49, 3.14159, and "boo". The usual hexadecimal, octal, and binary integral formats (e.g., 0x23, 023, and 0b011 respectively) are also supported. The usual string escapes as well as the Unicode escape are supported:
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>\t, \n, \r, \\, \", and \u03a9
+</PRE>
+</DIV></DIV></LI>
+ <LI>Identifiers are used to specify the name of the service, each message, parameter, custom type, and constant. An identifier is composed of ASCII characters, may start with an upper or lowercase alphabetic, and may contain upper and lower case alphabetic, numeric, or underscore characters. While not enforced (yet), the recommended style is that service, enum, struct, exception, and externnames should start with uppercase and use camel case conventions (e.g., FastCar, BlackCatWalking, etc.). Message and parameter names should start with lowercase and use camel case conventions (e.g., makeCall, sendName, etc.). Constants and enum elements should be all uppercase with underscores (e.g., FISH_SOUP, STALE_BREAD, etc.).</LI>
+ <LI>Definitions may be terminated by a semi-colon ( ";" ) but that is totally optional.</LI>
+ <LI>Comments may be the standard Java types:
+ <UL>
+ <LI>// causes the rest of the line to be ignored.</LI>
+ <LI>/* blah */ causes blah to be ignored; may extend over multiple lines; may not be nested.</LI>
+ <LI>/** blah */ is a formal comment. Adds a description to the following definition (if allowed). Follows Javadoc style. Descriptions are copied into the generated interfaces.</LI>
+ </UL>
+ </LI>
+</UL>
+
+
+<H1><A name="LanguageReference-NativeDataTypes"></A>Native Data Types</H1>
+
+<P>The native types include:</P>
+<UL>
+ <LI>boolean - true or false</LI>
+ <LI>byte - signed 8-bit quantity (-2^7 to 2^7-1)</LI>
+ <LI>short - signed 16-bit quantity (-2^15 to 2^15-1)</LI>
+ <LI>int - signed 32-bit quantity (-2^31 to 2^31-1)</LI>
+ <LI>long - signed 64-bit quantity (-2^63 to 2^63-1)</LI>
+ <LI>float - single precision IEEE floating point (max 3.4028235e38)</LI>
+ <LI>double - double precision IEEE floating point (max 1.7976931348623157e308)</LI>
+ <LI>string - sequence of characters (generally, Unicode), arbitrary length</LI>
+</UL>
+
+
+<P>These types correspond to the architectural types found on almost all computer systems.</P>
+
+<H1><A name="LanguageReference-ExtendedTypes"></A>Extended Types</H1>
+
+<P>Common extended types are also included.</P>
+
+<H2><A name="LanguageReference-Datetime"></A>Datetime</H2>
+
+<P>Datetime represents a specific moment in time.</P>
+
+<H3><A name="LanguageReference-Examples"></A>Examples</H3>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>Datetime timeSaved;
+boolean isSunday ( Datetime time )
+</PRE>
+</DIV></DIV>
+
+<H2><A name="LanguageReference-List"></A>List</H2>
+
+<P>A List represents an ordered collection of values.</P>
+
+<H3><A name="LanguageReference-Examples"></A>Examples</H3>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>List values;
+object getLastValue ( List list )
+</PRE>
+</DIV></DIV>
+
+<H2><A name="LanguageReference-Set"></A>Set</H2>
+
+<P>A Set represents an unordered collection of unique values.</P>
+
+<H3><A name="LanguageReference-Examples"></A>Examples</H3>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>Set values;
+boolean addValueToSet ( Set set, object value )
+</PRE>
+</DIV></DIV>
+
+<H2><A name="LanguageReference-Map"></A>Map</H2>
+
+<P>A Map represents a set of keys, each of which points to a value.</P>
+
+<H3><A name="LanguageReference-Example"></A>Example</H3>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>boolean addPair ( Map map, object key, object value )
+</PRE>
+</DIV></DIV>
+
+<H1><A name="LanguageReference-ObjectDataType"></A>Object Data Type</H1>
+
+<P>An <B>object</B> is used to model a parameter or result where the actual type is determined at runtime. An object type specification may be used anywhere a native data type is allowed except when declaring constants.</P>
+
+<H3><A name="LanguageReference-Examples"></A>Examples</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>struct ValueList ( string name, object[] values )
+exception BadValue ( int id, string msg, object value )
+object getValue ( string name )
+object[] setValue ( string name, object value )
+</PRE>
+</DIV></DIV>
+
+<H2><A name="LanguageReference-Constants"></A>Constants</H2>
+
+<P>A constant declaration is used to include named values into the generated interfaces. There is no messaging component associated with them, just a handy way to define a named value which is available to each implementation in appropriate target syntax.</P>
+
+<P>The value of the constant must be appropriate for the type.</P>
+
+<P>Constant names are by convention all uppercase, with underscore used to separate words.</P>
+
+<H3><A name="LanguageReference-Syntax"></A>Syntax</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE><const_stmt> ::= "const" <ctype> <id> "=" <cvalue> (";")?
+<ctype> ::= "boolean" | "byte" | "short" | "int" | "long" | "float" | "double" | "string"
+<cvalue> ::= "true" | "false" | <integer> | <octal> | <hex> | <binary> | <decimal> | <string>
+</PRE>
+</DIV></DIV>
+
+<H3><A name="LanguageReference-Examples"></A>Examples</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>const int MAX_NAME_LENGTH = 31
+const string USER_NAME = "Fred"
+const float PI = 3.14159
+</PRE>
+</DIV></DIV>
+
+<H2><A name="LanguageReference-Enumerations"></A>Enumerations</H2>
+
+<P>An enumeration is used to declare a type which has a named set of values. These are most often used where the set of values is small. Some languages use integers to model enumerations while others use tokens (identifiers) and yet others use object instances.</P>
+
+<P>Enumeration names are by convention capitalized. Enumeration item names are all uppercase.</P>
+
+<H3><A name="LanguageReference-Syntax"></A>Syntax</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE><enum_stmt> ::= "enum" <id> "(" <id> ("," <id>)* ")" (";")?
+</PRE>
+</DIV></DIV>
+
+<H3><A name="LanguageReference-Examples"></A>Examples</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>enum State ( OPEN, CLOSED )
+enum RGBColor ( RED, GREEN, BLUE )
+</PRE>
+</DIV></DIV>
+
+<H2><A name="LanguageReference-StructuredType"></A>Structured Type</H2>
+
+<P>A structure is used to model a small set of named parameters of heterogeneous type. When a structure contains another structure as a parameter it is by reference. Thus, in Etch, a structure may contain itself (directly or indirectly) as a parameter (if the containment was by value, a structure could not contain itself because that would introduce a storage recursion).</P>
+
+<P>Structure names are by convention capitalized. Parameter names are by convention lowercase.</P>
+
+<P>Strangely enough, a structure might not have any parameters. This might seem silly, but the mere presence of the structure might be used like a boolean to assert a condition (that is, indicate the condition is true, whereas null indicates the condition is false), while allowing for future expansion by adding parameters to the structure.</P>
+
+<P>Note that <ptype> includes the native types as well as <id>, <qid>, and <object>. The <id> or <qid> is used to indicate a custom type name. An <object> is used to model a parameter or result where the actual type is determined at runtime.</P>
+
+<P>A structure may extend another structure. In this way the structure inherits the parameters and identity of the extended structure. This is functionally equivalent to class inheritance in java, csharp, ruby, etc.</P>
+
+<P>There are some rules:</P>
+<OL>
+ <LI>a structure may not extend another such that an inheritance loop is created.</LI>
+ <LI>a structure may not declare a parameter whose name is the same as any already in its inheritance.</LI>
+</OL>
+
+
+<H3><A name="LanguageReference-Syntax"></A>Syntax</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE><struct_stmt> ::= "struct" <id> <params> ( "extends> <id> )? ( ";" )?
+<params> ::= "(" ( <param> ( "," <param> )* )? ")"
+<param> ::= <ptype> <dim> <id>
+<ptype> ::= <ctype> | "object" | <ref>
+<dim> ::= ( "[]" )*
+<ref> ::= <xid>
+<xid> :: = <qid> | <id>
+<qid> :: = <ID> ("." <ID>)+>
+</PRE>
+</DIV></DIV>
+
+<H3><A name="LanguageReference-Examples"></A>Examples</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>struct Point ( int x, int y )
+struct Path ( Point[] points )
+struct AsyncAction () extends Action
+</PRE>
+</DIV></DIV>
+
+<H2><A name="LanguageReference-Arrays"></A>Arrays</H2>
+
+<P>As you can see in <param>, above, a parameter in a structure may be dimensioned. The number of square bracket pairs indicates the dimensionality. None indicates a scalar parameter. There is no particular limit on the number of dimensions you may have or the size of any particular dimension. Let your common sense guide you, keeping in mind all the possible language bindings there might be.</P>
+
+<H3><A name="LanguageReference-Examples"></A>Examples</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>int[] x // single dimensional array of int.
+Point[][] grid // two-dimensional array of Point.
+</PRE>
+</DIV></DIV>
+
+<H2><A name="LanguageReference-ExternalType"></A>External Type</H2>
+
+<P>Sometimes you really need to be able to reference a target language specific type in the NSDL. When you do, you must think carefully about the applicability to other language bindings that may want or need to use your service. Many useful types have analogs in the other languages anyway, such as Java's HashMap, ArrayList, and Date types. Note that Etch cannot model abstract or generic types, and so where abstracts or generics are involved they must be made concrete. In Java, StrIntMap instead of HashMap<String, Integer>, HashMap, or even Map:</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>package project.util;
+
+import java.util.HashMap;
+
+public class StrIntMap extends HashMap<String, Integer>
+{
+ // nothing else needed
+}
+</PRE>
+</DIV></DIV>
+<P>When you specify the external type, you import it into Etch by giving it a name that you will use inside Etch to reference it. Then for each language binding, you supply information about what the concrete type is and how to serialize / de-serialize it.</P>
+
+<P>Note: the @Extern annotation, along with all the other annotations, is described later. It is only shown here because otherwise the example of extern would be too vague. See the appendix for an extern example.</P>
+
+<H3><A name="LanguageReference-Syntax"></A>Syntax</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE><extern_stmt> ::= "extern" <id> (";")?
+</PRE>
+</DIV></DIV>
+
+<H3><A name="LanguageReference-Examples"></A>Examples</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>@Extern("java", "project.util.StrIntMap", "", "project.util.StrIntMapSerializer", "")
+extern StrIntMap
+</PRE>
+</DIV></DIV>
+
+<H2><A name="LanguageReference-Exceptions"></A>Exceptions</H2>
+
+<P>Exceptions are a special kind of struct which are an alternative response to a message execution. An exception cannot be a parameter or result of a message, nor a parameter in a structure.</P>
+
+<P>When a program wants to return an exception in Java, it creates an instance of the exception and throws it (compare this with creating an instance of a normal type and returning it). The throw operation, unlike return, can be performed deep in the call chain and terminates each call up the chain until caught by a handler. Return, on the other hand, can only terminate one call up the call chain and makes its value available to the next level up.</P>
+
+<P>In some programming languages (e.g., Java) exceptions are checked: a method cannot throw a checked exception unless it has declared that it might. Unchecked exceptions can always be thrown, and usually correspond to low-level conditions such as an attempt to use a null pointer, index an array element which doesn't exist, etc. In other programming languages (e.g., C#, Ruby, Python), all exceptions are unchecked. Some programming languages (e.g., C) do not have a concept of exception whatsoever.</P>
+
+<P>Etch reflects this by requiring methods to declare thrown exceptions. In this way the declarations may be passed through to programming languages which require the declarations. Of course, it is good for the users of a service to know which exceptions a particular message might throw.</P>
+
+<P>Note: exceptions should include at least some detail as to the cause, enough to suggest a solution of the problem. In messaging systems this is especially important, as a client often does not have enough access to the server to debug a problem from the server side. As you might expect, an exception with a simple message "parameter x (value 23) is not in the expected range (1-10)" is way more helpful than "value out of range". Furthermore, localization considerations might dictate that you declare an exception like this:</P>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>Exception IntOutOfRange( string name, int value, int min, int max )
+</PRE>
+</DIV></DIV>
+
+<P>and let the receiver format it as they wish. (But, that can get messy really fast!)</P>
+
+<P>Like structures, exception may extend other exceptions. See the discussion under structures,above.</P>
+
+<H3><A name="LanguageReference-Syntax"></A>Syntax</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE><except_stmt> ::= "exception" <id> <params> ( "extends> <ref> )? ( ";" )?
+<ref> ::= <xid>
+<xid> :: = <qid> | <id>
+<qid> :: = <ID> ("." <ID>)+>
+</PRE>
+</DIV></DIV>
+
+<H3><A name="LanguageReference-Examples"></A>Examples</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>exception BadArgument( string name, string reason )
+exception NoAuthorization( string name, string reason )
+</PRE>
+</DIV></DIV>
+
+<H2><A name="LanguageReference-Messages"></A>Messages</H2>
+
+<P>Messages describe the actual network traffic between the clients and servers. We use function definition syntax but the elements are the same: a message type and parameters (names and types).</P>
+
+<P>Message declarations actually describe two messages (if the message is two-way). The first is the request message which includes the message type and parameters with argument values. The second is the response message which includes the response message type and the result parameter and value.</P>
+
+<P>Messages can terminate normally by returning a value or they can terminate abnormally by throwing an exception. Either type of termination will return a response message from the remote process (again, unless the message is declared one-way).</P>
+
+<P><B>NOTE:</B> The vast majority of modern programming languages support exceptions; those that do not will need to accommodate the dual nature of the response message.</P>
+
+<P><B>NOTE:</B> One-way messages must have a void result type and not throw any exceptions.</P>
+
+<P>Message names and parameter names by convention start with a lowercase alphabetic, then use camel case.</P>
+
+<H3><A name="LanguageReference-Syntax"></A>Syntax</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE><message_stmt> ::= <rtype> <id> <params> (<throws>)? (";")?
+<rtype> ::= ( <ptype> <dim> ) | "void"
+<throws> ::= "throws" <ref> ( "," <ref> )*
+<ref> ::= <xid>
+<xid> :: = <qid> | <id>
+<qid> :: = <ID> ("." <ID>)+>
+</PRE>
+</DIV></DIV>
+
+<H3><A name="LanguageReference-Examples"></A>Examples</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>int add( int x, int y )
+Date getBirthday( string name ) throws NameNotFound
+Location[] getBestPath( Location[] locations ) throws NoSuchPath
+void report( Date when, EventType type, string detail )
+</PRE>
+</DIV></DIV>
+
+<H2><A name="LanguageReference-Includes"></A>Includes</H2>
+<P>You many add an include to to an etch servicde function.</P>
+
+<H3><A name="LanguageReference-Syntax"></A>Syntax</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE><inlcude> ::= "inlcude" <filename> (";")?
+</PRE>
+</DIV></DIV>
+
+<H3><A name="LanguageReference-Example"></A>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>
+
+<H5><A name="LanguageReference-testincl.txt"></A>testincl.txt</H5>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>
+const int INT2 = -2147483648;
+include "testincl1.txt";
+</PRE>
+</DIV></DIV>
+
+<H2><A name="LanguageReference-Mixin"></A>Mixin</H2>
+
+<P>A mixin is the mechanism used to incorporate the messages and types defined within another service into the current service. To the extent possible the original service retains its identity, such that with an object oriented language such as Java, C#, or Ruby, an instance of the current service could be passed where an instance of the mixed in service is expected. This facilitates the creation of reusable service libraries. You can have as many mixins as you like (up to the limit imposed by the various language bindings).</P>
+
+<P>Two examples of a mixin are an authentication service and an event service. These could be standard components for a deployment of a suite of other services. You only have to define them once, then you can add them to each of your other services as you like.</P>
+
+<H3><A name="LanguageReference-Syntax"></A>Syntax</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE><mixin_stmt> ::= "mixin" <ref> (";")?
+<ref> ::= <xid>
+<xid> :: = <qid> | <id>
+<qid> :: = <ID> ("." <ID>)+>
+</PRE>
+</DIV></DIV>
+
+<H3><A name="LanguageReference-Examples"></A>Examples</H3>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>module etch.bindings.csharp.compiler.test
+
+@Direction(Both)
+service MixinTest
+{
+ mixin NestedMixin
+ @Authorize(isLoggedIn)
+ int add( int x, int y )
+
+ @Authorize(isLoggedIn)
+ int sub( int x, int y )
+
+ void testRef(test t) throws Excp2
+
+
+}
+</PRE>
+</DIV></DIV>
+
+<H5><A name="LanguageReference-NestedMixin"></A>NestedMixin</H5>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>module etch.bindings.csharp.compiler.test
+
+@Direction(Both)
+service NestedMixin
+{
+
+ struct test (
+ string name,
+ string value
+ )
+
+ @Unchecked
+ exception Excp2()
+
+
+ void login( string name, string pw )
+
+ void logout()
+
+ boolean isLoggedIn()
+
+}
+</PRE>
+</DIV></DIV>
+
+<H4><A name="LanguageReference-ImportantNotes"></A>Important Notes</H4>
+
+<UL>
+ <LI>The mixin etch file must be present in the Include Path. In the above example, NestedMixin must be present in the Include Path. If the include path is not specified, then the Mixin etch file will only be searched in the current directory. Thus in the above example, if -I option (include option) is not specified, then NestedMixin will only be searched in the directory in which MixinTest is present.</LI>
+ <LI>When a user compiles the etch file which contains the mixin (TestMixin.etch in the above example), he can chose whether he wants the mixin artifacts to be generated or not. If he chooses not to generate the artifacts, then he must specify -n command line option If he chooses to generate the mixin artifacts then he must specify either -m or -d option (Please refer to the Etch Compiler Guide for more details on these options). Failure to specify either one of these option will lead to compilation problem.</LI>
+</UL>
+
+
+
+
+<H2><A name="LanguageReference-Service"></A>Service</H2>
+
+<P>All the definitions above are packaged into a service, which provides a naming scope. The compiler uses the features available in each language binding to create the naming scope. For example, in Java, the compiler creates a number of interfaces and classes with names derived from the service name.</P>
+
+<H3><A name="LanguageReference-Syntax"></A>Syntax</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px; width: 800px"><DIV class="preformattedContent panelContent">
+<PRE><service> ::= opts "service" <id> "{" ( <stmt> )* "}"
+opts ::= (opt)*
+opt ::= @ id (args)?
+args ::= arg (, arg )*
+arg ::= ( cvalue | xid | <NULL> )
+cvalue ::= ( <TRUE> | <FALSE> | <INTEGER> | <OCTAL> | <HEX> | <BINARY> | <DECIMAL> | <STR> )
+xid ::= ( qid | id )
+<qid> :: = <ID> ("." <ID>)+>
+<stmt> ::= <const_stmt> | <enum_stmt> | <struct_stmt> | <extern_stmt> | <except_stmt> | <message_stmt> | <mixin_stmt>
+</PRE>
+</DIV></DIV>
+
+<H3><A name="LanguageReference-Example"></A>Example</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>service DigestAuth
+{
+ exception LoginFailure( string msg )
+ string getSeed()
+ void login( string name, string seed, string digest )
+ throws LoginFailure
+ void logout()
+ boolean isLoggedIn()
+}
+</PRE>
+</DIV></DIV>
+
+<H2><A name="LanguageReference-Annotations"></A>Annotations</H2>
+
+<P>Annotations may be applied to a <stmt> to alter its behavior. Where it makes sense, you can even apply an annotation to the <service> to set the global behavior or defaults. See below for descriptions of supported annotations.</P>
+
+<H3><A name="LanguageReference-Syntax"></A>Syntax</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>opts ::= (opt)*
+opt ::= @ id (args)?
+args ::= arg (, arg )*
+arg ::= ( cvalue | xid | <NULL> )
+cvalue ::= ( <TRUE> | <FALSE> | <INTEGER> | <OCTAL> | <HEX> | <BINARY> | <DECIMAL> | <STR> )
+xid ::= ( qid | id )
+<qid> :: = <ID> ("." <ID>)+>
+</PRE>
+</DIV></DIV>
+
+<H3><A name="LanguageReference-Examples"></A>Examples</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>@Timeout( 4000 )
+@Direction( Server )
+Date getBirthday( string name )
+</PRE>
+</DIV></DIV>
+
+<H2><A name="LanguageReference-Module"></A>Module</H2>
+
+<P>The last bit of syntax is the module. This appears in the NSDL file before the service and defines the global namespace of the service. This has a very strong correlation to the Java package or the C# namespace, and a looser correlation to the Ruby module. It also contributes to the fully qualified name of the service itself, which is used to distinguish the service from other like-named services.</P>
+
+<H3><A name="LanguageReference-Syntax"></A>Syntax</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE><module> ::= "module" (<qid> | <id>) (";")? <service>
+</PRE>
+</DIV></DIV>
+
+<H3><A name="LanguageReference-Examples"></A>Examples</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>module project.auth
+
+service DigestAuth
+
+{
+
+...
+
+}
+</PRE>
+</DIV></DIV>
+
+<H1><A name="LanguageReference-SupportedAnnotations"></A>Supported Annotations</H1>
+
+
+<H2><A name="LanguageReference-@AsyncReceiver"></A>@AsyncReceiver</H2>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>@AsyncReceiver( NONE | QUEUED | FREE )
+</PRE>
+</DIV></DIV>
+<P>Specifies that the processing mode used by the server for this message or the default processing mode for all the messages of the service. A specification on a message overrides the service default.</P>
+<UL>
+ <LI>NONErequests the message be delivered on the message receiver thread. While this message is being processed, no other message may be read and delivered. Messages are processed in the order received.</LI>
+ <LI>QUEUEDrequests the message be queued to a thread pool for delivery. This is generally used by operations which complete relatively quickly but might want to dialog with the caller using callbacks, or perform some other operation which might briefly block.</LI>
+ <LI>FREErequests the message be delivered by a newly created free thread. This is generally used by long running operations.</LI>
+</UL>
+
+
+<H3><A name="LanguageReference-Default"></A>Default</H3>
+
+<P>The service default is NONE.</P>
+
+<H3><A name="LanguageReference-MayBeAppliedTo"></A>May Be Applied To</H3>
+
+<P><message_stmt>, <service></P>
+
+<H3><A name="LanguageReference-Example"></A>Example</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>// run add asynchronously on a queued pool thread.
+@AsyncReceiver( QUEUED )
+
+int add( int x, int y )
+
+</PRE>
+</DIV></DIV>
+
+<H2><A name="LanguageReference-@Authorize"></A>@Authorize</H2>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE> @Authorize[( method [, arg ...] )] </PRE>
+</DIV></DIV>
+
+<P>Specifies that the message receiver should use the specified method to determine whether the message is allowed to be processed, or set the service default authorization method for all messages in the service. Method should be a service message declared the same direction as this message and returning a boolean result. An exception will be thrown by the receiver if the message is not allowed. A specification on a message overrides the service default.</P>
+
+<P>The args are a sequence of named or unnamed constants, enumeration values, or message parameters or parameters of parameters, etc., corresponding in number, order, and type to the signature of method.</P>
+
+
+<P>Method true always allows the message, while falsenever allows the message. Neither of these are allowed any args.</P>
+
+<H3><A name="LanguageReference-Default"></A>Default</H3>
+
+<P>The service default is true. If specified without an argument, true is assumed.</P>
+
+<H3><A name="LanguageReference-MayBeAppliedTo"></A>May Be Applied To</H3>
+
+<P><message_stmt>, <service></P>
+
+<H3><A name="LanguageReference-Example"></A>Example</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>// only allow logged in users to delete files.
+@Authorize( isLoggedIn )
+
+void deleteFile( string name )
+
+// returns true if a user is logged in.
+boolean isLoggedIn()
+
+// only allow the admin of the specified user to grant rights.
+@Authorize( isAdminOf, userName)
+void grantRight( string userName, string right )
+
+// returns true if the current user is the admin of the
+// specified user. isAdminOf should test isLoggedIn first.
+boolean isAdminOf( string userName )
+
+// don't let anyone send this message for now.
+@Authorize( false )
+
+void rmDashRFSlash()
+
+</PRE>
+</DIV></DIV>
+
+<H2><A name="LanguageReference-@Direction"></A>@Direction</H2>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE> @Direction( SERVER | CLIENT | BOTH ) </PRE>
+</DIV></DIV>
+<P>Specifies the direction of the message, or sets the service default direction for all messages in the service:</P>
+<UL>
+ <LI>SERVER means from the client to the server.</LI>
+ <LI>CLIENT means from the server to the client (a callback).</LI>
+ <LI>BOTH means either client or server may send the message to the other.</LI>
+</UL>
+
+
+<P>A specification on a message overrides the service default.</P>
+
+<H3><A name="LanguageReference-Default"></A>Default</H3>
+
+<P>The service default is SERVER.</P>
+
+<H3><A name="LanguageReference-MayBeAppliedTo"></A>May Be Applied To</H3>
+
+<P><message_stmt>, <service></P>
+
+<H3><A name="LanguageReference-Example"></A>Example</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>// notify the client that a user's status has changed.
+@Direction( CLIENT )
+
+void statusUpdate( string userName, boolean online )
+</PRE>
+</DIV></DIV>
+<H2><A name="LanguageReference-@Extern"></A>@Extern</H2>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE> @Extern( language, name, nImport, serializer, sImport ) </PRE>
+</DIV></DIV>
+<P>Declares language binding and serializer for an external type. Language is a compiler supported name for a binding (e.g., java, csharp, ruby); name is the language specific name of the type to use; nImport is a string that must be used in something like an import or requires statement to make name available; serializer is the language specific name of the type to use to import and export (this type must declare certain specific methods); sImport is a string that must be used in something like an import, using, include, or require statement to make serializer available.</P>
+
+<H3><A name="LanguageReference-Default"></A>Default</H3>
+
+<P>There is no default. If NSDL is compiled for a language which has no binding for an external type, the compilation will fail.</P>
+
+<H3><A name="LanguageReference-MayBeAppliedTo"></A>May Be Applied To</H3>
+
+<P><extern_stmt></P>
+
+<H3><A name="LanguageReference-Example"></A>Example</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>// for java, map Date to java.util.Date and use
+// project.util.DateSerializer to serialize and
+// deserialize the object.
+
+@Extern( java, "java.util.Date", "",
+
+"project.util.DateSerializer", "" )
+
+// for csharp, map Date to System.DateTime, and
+// use project.util.DateTimeSerializer to serialize
+// and deserialize the object.
+
+@Extern( csharp, "System.DateTime", "", "project.util.DateTimeSerializer", "" )
+
+// for ruby, map Date to Time, and use TimeSerializer
+// from project/util/time_serializer.rb to serialize
+// and deserialize the object.
+
+@Extern( ruby, "Time", "", "TimeSerializer", "project/util/time_serializer" )
+
+extern Date
+</PRE>
+</DIV></DIV>
+<H2><A name="LanguageReference-@Oneway"></A>@Oneway</H2>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE> @Oneway[( true | false )] </PRE>
+</DIV></DIV>
+<P>Specifies that the sender of this message does not wait for any response, or specifies the service default for all messages. This is sometimes called a fire-and-forget message, and some other times called an event message. Such a message must be declared to have a void result, and may not be declared to throw any exceptions. A specification on a message overrides the service default.</P>
+
+<H3><A name="LanguageReference-Default"></A>Default</H3>
+
+<P>The service default is false. If specified without an argument, true is assumed.</P>
+
+<H3><A name="LanguageReference-MayBeAppliedTo"></A>May Be Applied To</H3>
+
+<P><message_stmt>, <service></P>
+
+<H3><A name="LanguageReference-Example"></A>Example</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>// notify the client that a user's status has changed.
+// don't wait for any response.
+@Direction( CLIENT ) @Oneway
+
+void statusUpdate( string userName, boolean online )
+</PRE>
+</DIV></DIV>
+<H2><A name="LanguageReference-@Timeout"></A>@Timeout</H2>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE> @Timeout( ms ) </PRE>
+</DIV></DIV>
+<P>Specifies the time in milliseconds for the sender of a message to wait for a response, or specifies the service default timeout for all messages. Timeout of '0' means wait forever. A specification on a message overrides the service default.</P>
+
+<H3><A name="LanguageReference-Default"></A>Default</H3>
+
+<P>The service default is .</P>
+
+<H3><A name="LanguageReference-MayBeAppliedTo"></A>May Be Applied To</H3>
+
+<P><message_stmt>, <service></P>
+
+
+<H3><A name="LanguageReference-Example"></A>Example</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>// wait 30 seconds for mom to respond, then if
+// she doesn't, decide whether to go anyway...
+@Timeout( 30000 )
+
+boolean getPermission( "Mom, can I go to the movie with Fred?" )
+</PRE>
+</DIV></DIV>
+<H2><A name="LanguageReference-@ToString"></A>@ToString</H2>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE> @ToString( fmt ) </PRE>
+</DIV></DIV>
+<P>Specifies a format specifier for language specific "to string" methods. The "to string" methods are written in the appropriate way for the target languages. Why "to string" methods? They are needed for debugging and logging.</P>
+
+<H3><A name="LanguageReference-Default"></A>Default</H3>
+
+<P>The default is "param1={param1}, ..." for each parameter of the struct or exception.</P>
+
+<H3><A name="LanguageReference-MayBeAppliedTo"></A>May Be Applied To</H3>
+
+<P><struct_stmt>, <except_stmt></P>
+
+<H3><A name="LanguageReference-Example"></A>Example</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>@ToString( "Point({x}, {y})" )
+
+struct Point( int x, int y )
+</PRE>
+</DIV></DIV>
+<H2><A name="LanguageReference-@Unchecked"></A>@Unchecked</H2>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE> @Unchecked[( true | false)] </PRE>
+</DIV></DIV>
+<P>In languages with checked exceptions, specifies than an exception should be unchecked, or specifies that the service default for exceptions should be unchecked.</P>
+
+<H3><A name="LanguageReference-Default"></A>Default</H3>
+
+<P>The service default is false. If specified without an argument, true is assumed.</P>
+
+<H3><A name="LanguageReference-MayBeAppliedTo"></A>May Be Applied To</H3>
+
+<P><except_stmt>, <service></P>
+
+<H3><A name="LanguageReference-Example"></A>Example</H3>
+
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>@Unchecked
+exception AuthException( string name, string reason )
+</PRE>
+</DIV></DIV>
+
+<H1><A name="LanguageReference-FormalComments"></A>Formal Comments</H1>
+
+<P>Formal comments are used to describe each Etch service description element. The descriptions are copied over into the generated files so that they are available to the programmers in their natural environments. Here is a simple example:</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>/**
+* The HydroMath service uses an atomic-powered highly-advanced
+* hydrostatic processor to perform astounding binary
+* manipulations.
+*/
+
+service HydroMath
+{
+
+ /**
+ * Exception thrown if the hydrostatic processor
+ * encounters a problem.
+ * @param code the problem description code.
+ */
+ exception OverflowException( int code )
+
+ /**
+ * Returns the sum of x and y.
+ * @param x input value.
+ * @param y input value.
+ * @return the sum of x and y.
+ * @throws OverflowException if the hydrostatic
+ * processor encounters a problem.
+ */
+ void add( int x, int y ) throws OverflowException
+}
+</PRE>
+</DIV></DIV>
+<P>This produces (for the java target) the following output:</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>/**
+ * Exception thrown if the hydrostatic processor
+ * encounters a problem.
+ */
+public class OverflowException extends Exception
+{
+ /**
+ * Constructs the OverflowException.
+ * @param code the problem description code.
+ */
+ public OverflowException( Integer code )
+ {
+ this.code = code;
+ }
+
+ /**
+ * the problem description code. RTFM.
+ */
+ public Integer code;
+}
+
+/**
+* The HydroMath service uses an atomic-powered highly-advanced
+* hydrostatic processor to perform astounding binary
+* manipulations.
+*/
+public interface HydroMathServer extends HydroMath
+{
+ /**
+ * Returns the sum of x and y.
+ * @param x input value.
+ * @param y input value.
+ * @return the sum of x and y.
+ * @throws OverflowException if the hydrostatic
+ * processor encounters a problem.
+ */
+ public Integer add( Integer x, Integer y ) throws OverflowException;
+}
+</PRE>
+</DIV></DIV>
+<P>A formal comment may be attached to:</P>
+<UL>
+ <LI>Service</LI>
+ <LI>Constant</LI>
+ <LI>Enumeration</LI>
+ <LI>Enumeration element</LI>
+ <LI>Structure</LI>
+ <LI>Exception</LI>
+ <LI>Message</LI>
+ <LI>Parameter of a structure, exception, or message</LI>
+ <LI>Exception thrown by a message</LI>
+</UL>
+
+
+<P>The formal comment is started by the /<B>* sequence, and terminated by the */ sequence. The contents, minus internal sequences that look like <eol><whitespace></B><whitespace> are attached to the element in question.</P>
+
+<P>A parameter of a structure, exception, or message may be commented two ways. The Javadoc style was shown in the HydroMath example above. The second style is shown here:</P>
+<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>/** @return the sum of x and y. */
+int add(
+
+ /** input value. */
+ int x,
+
+ /** input value. */
+ int y
+
+) throws
+
+ /** if the hydrostatic processor encounters a problem. */
+ OverflowException
+</PRE>
+</DIV></DIV>
+<P>The body of the formal comment is taken whole for elements except for a structure, exception, or message. For those the body is scanned looking for @param tags, and for a message, @return or @throws tags. If / when one of those tags is found, the main description is terminated and text is spooled to the description of the sub-element. In all cases the descriptions may span multiple lines.</P>
+
+<H3><A name="LanguageReference-@param%3Cname%3E%3Cdescr%3E"></A>@param <name> <descr></H3>
+
+<P>The name must specify the name of a structure, exception, or message.</P>
+
+<H3><A name="LanguageReference-@return%3Cdescr%3E"></A>@return <descr></H3>
+
+<P>The message must be defined to return a value.</P>
+
+<H3><A name="LanguageReference-@throws%3Cname%3E%3Cdescr%3E"></A>@throws <name> <descr></H3>
+
+<P>The name must specify the name of an exception that the message throws.</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/overview.html
==============================================================================
--- websites/staging/etch/trunk/content/etch/documentation/overview.html (added)
+++ websites/staging/etch/trunk/content/etch/documentation/overview.html Thu Dec 15 14:36:04 2011
@@ -0,0 +1,248 @@
+
+<!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>Overview</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.rbtoc1284535220451 {margin-left: 0px;padding: 0px;}
+div.rbtoc1284535220451 ul {list-style: none;margin-left: 0px;}
+div.rbtoc1284535220451 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</STYLE><DIV class="rbtoc1284535220451">
+<UL>
+ <LI><SPAN class="TOCOutline">1</SPAN> <A href="#Overview-Abstract">Abstract</A></LI>
+ <LI><SPAN class="TOCOutline">2</SPAN> <A href="#Overview-ProblemSolved">Problem Solved</A></LI>
+ <LI><SPAN class="TOCOutline">3</SPAN> <A href="#Overview-NetworkServiceDescriptionLanguage">Network Service Description Language</A></LI>
+ <LI><SPAN class="TOCOutline">4</SPAN> <A href="#Overview-LanguageIndependentMessaging">Language Independent Messaging</A></LI>
+ <LI><SPAN class="TOCOutline">5</SPAN> <A href="#Overview-TransportIndependence">Transport Independence</A></LI>
+ <LI><SPAN class="TOCOutline">6</SPAN> <A href="#Overview-MessageDefinition">Message Definition</A></LI>
+ <LI><SPAN class="TOCOutline">7</SPAN> <A href="#Overview-ServiceExtensionandVersioning">Service Extension and Versioning</A></LI>
+ <LI><SPAN class="TOCOutline">8</SPAN> <A href="#Overview-FundamentalDataTypes">Fundamental Data Types</A></LI>
+ <LI><SPAN class="TOCOutline">9</SPAN> <A href="#Overview-ExtendedDataTypes">Extended Data Types</A></LI>
+ <LI><SPAN class="TOCOutline">10</SPAN> <A href="#Overview-ExternalDataTypes">External Data Types</A></LI>
+ <LI><SPAN class="TOCOutline">11</SPAN> <A href="#Overview-NamedConstants">Named Constants</A></LI>
+ <LI><SPAN class="TOCOutline">12</SPAN> <A href="#Overview-ImplementationDetails">Implementation Details</A></LI>
+ <LI><SPAN class="TOCOutline">13</SPAN> <A href="#Overview-BinaryTransport">Binary Transport</A></LI>
+ <LI><SPAN class="TOCOutline">14</SPAN> <A href="#Overview-Footprint">Footprint</A></LI>
+ <LI><SPAN class="TOCOutline">15</SPAN> <A href="#Overview-Performance">Performance</A></LI>
+ <LI><SPAN class="TOCOutline">16</SPAN> <A href="#Overview-Roadmap">Roadmap</A></LI>
+</UL></DIV></DIV>
+<!--<span style="background-color:green">adfasdf</span>-->
+<H2><A name="Overview-Abstract"></A>Abstract</H2>
+<P>Etch is a cross-platform, network messaging system which includes a service description language, a compiler, and runtime for a variety of programming languages. Etch is transport independent, which allows for a variety of transports to be used depending upon need and circumstance.</P>
+
+<H2><A name="Overview-ProblemSolved"></A>Problem Solved</H2>
+
+<P>The Etch project was started because we wanted to have a way to write a concise, formal description of the message exchange between a client and a server, with a hefty set of requirements, including: the messaging technology should support two-way, real-time communication, have high performance and scalability, support clients and servers written in differing languages, support client / server running in wide range of contexts (such as thin web client, PC application, or server), and must support anyone (Cisco or not) adding new language bindings and new transports if the set provided by the Cisco Unified Application Environment team is not sufficient.</P>
+
+<P>Existing competing systems were either too slow, hard to use, bloated, and / or proprietary. In any case, none fit this matrix of requirements perfectly. So, Etch is designed to be easy to use, fast, and small; while still being flexible enough to satisfy the above requirements.</P>
+
+<P>SOAP / REST Web Services offer an interesting comparison by contrast. While Web Services are generally accepted as the de facto standard for cross-platform communication due to strong adoption across many tools and languages, the unfortunate reality is that Web Services have serious deficiencies which make them completely unusable for real-time communications. Specifically, Web Services have no effective way to communicate asynchronously from server to client due to a reliance on HTTP and have very high parsing overhead due to XML and SOAP message bodies. In some deployments server to client communication would be blocked by a firewall. Finally, any particular language usually does not support every aspect of Web Services, so it is completely possible to create a Web Service that is not, in fact, cross-platform.</P>
+
+<H2><A name="Overview-NetworkServiceDescriptionLanguage"></A>Network Service Description Language</H2>
+
+<P>The Etch service description language allows the messages of the service to be described using a concise, high-level programming language syntax. The NSDL describes messages; direction of the messages, message inputs and outputs, response timeouts, sender and receiver thread models, and authentication. The NSDL also allows for the specification of structured data, enumerated values, named constants, and exceptions. Comments written into the NSDL are copied into the generated native language files so that they are available to the programmers.</P>
+
+<H2><A name="Overview-LanguageIndependentMessaging"></A>Language Independent Messaging</H2>
+
+<P>Etch supports language independence by compiling language appropriate interfaces supported by libraries to send and receive the messages. External data types are defined and mapped to appropriate language specific runtime objects, supported by native serialization code.</P>
+
+<H2><A name="Overview-TransportIndependence"></A>Transport Independence</H2>
+
+<P>Etch service message descriptions and data are compiled into data structures which are used by the transport layer to format the messages for transport. All the information of the message is available to the transport layer. Transport is subdivided into message formatting, security, and protocol. Message formats include a compressed binary tagged format as well as XML. Security includes stream ciphers such as SSL / TLS and block ciphers such as DES or AES. Protocols include TCP, UDP (unicast, multicast, broadcast), and various SOAP formats. Other formats, security, and protocols are easily added.</P>
+
+<H2><A name="Overview-MessageDefinition"></A>Message Definition</H2>
+<P>A message is defined as a standard function call:</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+<SPAN class="code-object">int</SPAN> add( <SPAN class="code-object">int</SPAN> x, <SPAN class="code-object">int</SPAN> y )
+</PRE>
+</DIV></DIV>
+
+<P>It has a name and a list of typed fields. It may return a value and it may throw an exception. However, as Etch is a client / server network messaging technology – not purely in-memory code – network considerations must be made. So in addition there are attributes, or tags, that can further qualify messages for optimal performance and encourage correct programming paradigms. For instance, a message that has no need of a response (fire-and-forget) may be decorated as 'one-way':</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+@Oneway
+void endSession()
+</PRE>
+</DIV></DIV>
+
+<P>With a client & server, the direction of the message is of course important. By default, a message is assumed client-initiated; server-initiated messages (callbacks) must be decorated appropriately:</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+@Direction(client)
+void notify(MyStruct data)
+</PRE>
+</DIV></DIV>
+
+<P>Another important message attribute is authorization. For example, if a message should not be allowed unless a certain requirement is met, then the message is tagged with that requirement. In this way the requirement is made plain, and the programmers implementing the service cannot forget:</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+@Authorize(isLoggedIn)
+void deleteFile(string filename)
+</PRE>
+</DIV></DIV>
+
+<P>There are more attributes that can be used to further qualify the service messages.</P>
+
+<H2><A name="Overview-ServiceExtensionandVersioning"></A>Service Extension and Versioning</H2>
+
+<P>The Etch system is designed so that service descriptions may be extended or revised in ways that don't invalidate existing clients or servers. The rule is that changes following reasonable design disciplines do not invalidate the existing clients and servers.</P>
+
+<P>Etch does not formally define service versioning because versioning is too often idiomatic to a service or organization. At the same time, versioning is too blunt a tool and artificially increases the difficulty of deploying compatible system upgrades. The best practice is to be disciplined about changes to the service description and to provide interfaces to query feature availability (a la ODBC / JDBC, SMTP, POP, etc.)</P>
+
+<H2><A name="Overview-FundamentalDataTypes"></A>Fundamental Data Types</H2>
+
+<P>Etch includes support for the fundamental data types which appear in many processor architectures and databases: boolean, byte, short, int, long, float, double, and string. The integral values are all signed, with size from 1 to 8 bytes. The floating point values are all typically IEEE compatible, with size from 4 to 8 bytes. The string value is Unicode, with no specified length limit.</P>
+
+<P>Etch also supports arrays of any supported data type. The arrays may have one or more dimensions. The arrays conform to the Java style or jagged arrays.</P>
+
+<P>In addition, Etch supports the <B>object</B> data type which is used to model a parameter or result where the actual type is determined at runtime. An object type specification my be used anywhere a native data type is allowed except when declaring constants.</P>
+
+<H2><A name="Overview-ExtendedDataTypes"></A>Extended Data Types</H2>
+
+<P>Etch supports the definition of enumerated types. The enumerations are mapped by name, not by any particular value or order.</P>
+
+<P>Etch also supports the definition of structs and exceptions, which are very similar to message definitions (name, list of typed fields), although of course structs and exceptions do not have return values and cannot themselves throw exceptions.</P>
+
+<H2><A name="Overview-ExternalDataTypes"></A>External Data Types</H2>
+
+<P>Etch allows native language data types to be imported and used within the service definition. All that is needed is to give the type a name in the service description, then for each desired target language to nominate a type which carries the same semantics (java.util.Date in Java, System.DateTime in C#, Time in Ruby). A specific class which will perform the work of serializing and de-serializing the object must also be implemented per target language.</P>
+
+<H2><A name="Overview-NamedConstants"></A>Named Constants</H2>
+
+<P>Etch allows the definition of named constants of the fundamental data types. These do not appear in the protocol per se, but are copied into the generated files and are available to all target programming languages.</P>
+
+<H2><A name="Overview-ImplementationDetails"></A>Implementation Details</H2>
+
+<P>The Etch compiler generates for each target language meta-data defining the types and fields of your service, interface files which define the messages, structs, enums, exceptions, external data, constants, and other NSDL elements, and then code to support turning method (or, function) calls into message sends (the remote implementation) and code to support turning messages received back into method calls (the stub implementation).</P>
+
+<P>The compiler is implemented in Java and uses Velocity templates to generate the code. Thus the compiler is available to use on any Java enabled platform, although of course Java is not needed once the NSDL is compiled unless your application is written in Java. Once compiled, all your application need do is to link with the small Etch runtime written (more than likely) in the target programming language.</P>
+
+<H2><A name="Overview-BinaryTransport"></A>Binary Transport</H2>
+
+<P>The current Etch system includes a production-ready, compressed binary tagged message format with TCP and UDP transports, and a non-production ready XML transport in Java as an example. The binary transport includes a tag for every data element which describes the size and type (i.e., 4 byte integer stored as 1 byte). Struct types and fields are encoded as a 32-bit hash of the name. This saves space in the wire format over sending the complete names. The maximum size of the add message defined above is 49 bytes, including an 8 byte packet header and 8 byte message ID (but not IP / TCP header).</P>
+
+<H2><A name="Overview-Footprint"></A>Footprint</H2>
+
+<P>The Java implementation of the Etch runtime needed to support a service using the compressed binary tagged message format over TCP without encryption is 288k (compressed jar file).</P>
+
+<H2><A name="Overview-Performance"></A>Performance</H2>
+
+<P>Performance numbers are always tricky and subjective because so much depends upon the context of the test. That said, we have gone through the exercise of contrasting various messaging technologies against one another. In this test, we implemented the add function shown above in Etch (Java language binding), Apache Axis2 SOAP web service, JAX SOAP web services, Thrift (Java), and CORBA (Java):</P>
+
+<DIV class="table-wrap">
+<TABLE class="confluenceTable"><TBODY>
+<TR>
+<TD class="confluenceTd"> <B>System</B> </TD>
+<TD class="confluenceTd"> <B>Calls/Second</B> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> Etch Java </TD>
+<TD class="confluenceTd"> 13.3k </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> Thrift Java </TD>
+<TD class="confluenceTd"> 13.5k </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> Java RMI </TD>
+<TD class="confluenceTd"> 7.4k </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> CORBA Java </TD>
+<TD class="confluenceTd"> 2.4k </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> JAX-WS </TD>
+<TD class="confluenceTd"> 943 </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> Apache Axis2 </TD>
+<TD class="confluenceTd"> 206 </TD>
+</TR>
+</TBODY></TABLE>
+</DIV>
+
+
+
+<H2><A name="Overview-Roadmap"></A>Roadmap</H2>
+
+<P>A Python binding and some form of browser-Javascript binding have been implemented in first versions, but are not yet ready.</P>
+
+<P>We plan to build a language binding for web services such than an Etch NSDL may be accessed and / or deployed as a web service. This would allow easy migration of clients and / or servers to use Etch natively while maintaining backwards compatibility with existing systems.</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>