Added: websites/staging/ace/trunk/content/docs/coding-standards.html
==============================================================================
--- websites/staging/ace/trunk/content/docs/coding-standards.html (added)
+++ websites/staging/ace/trunk/content/docs/coding-standards.html Mon Nov 24
22:42:13 2014
@@ -0,0 +1,717 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+ <head>
+ <title>Coding Standards</title>
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ <meta property="og:image" content="//www.apache.org/images/asf_logo.gif" />
+ <link href="/css/bootstrap.min.css" rel="stylesheet" media="screen">
+ <link href="/css/prettify.css" rel="stylesheet" media="screen">
+ <link href="/css/code.css" rel="stylesheet" media="screen">
+ <script src="//code.jquery.com/jquery.js"></script>
+ <script src="/js/bootstrap.min.js"></script>
+ <script src="/js/prettify.js"></script>
+
+
+
+ <script>
+ $(function () { prettyPrint() })
+ $().dropdown()
+ </script>
+ </head>
+ <body style="padding-top: 50px;">
+ <div class="navbar navbar-fixed-top navbar-inverse">
+ <div class="navbar-inner">
+ <div class="container">
+ <a class="brand" href="/index.html">Apache ACE™</a>
+ <ul class="nav">
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">News <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="/news.html">News</a>
+ </li>
+ <li>
+ <a href="/on-the-web.html">On the web</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="/downloads.html">Downloads</a>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Users <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="/user-doc/introduction.html">Introduction</a>
+ </li>
+ <li>
+ <a href="/user-doc/getting-started.html">Getting Started</a>
+ </li>
+ <li>
+ <a href="/user-doc/user-guide.html">User Guide</a>
+ </li>
+ <li>
+ <a href="/user-doc/features.html">Features</a>
+ </li>
+ <li>
+ <a href="/user-doc/shellapi.html">Client Shell API</a>
+ </li>
+ <li>
+ <a href="/user-doc/restapi.html">Client REST API</a>
+ </li>
+ <li>
+ <a href="/user-doc/useradmin-ui.html">User Management Guide</a>
+ </li>
+ <li>
+ <a href="/user-doc/faq.html">FAQ</a>
+ </li>
+ <li>
+ <a href="/user-doc/support.html">Support</a>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Developers <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="/dev-doc/getting-started.html">Getting Started</a>
+ </li>
+ <li>
+ <a href="/dev-doc/requirements/">Requirements</a>
+ </li>
+ <li>
+ <a href="/dev-doc/architecture.html">Architecture</a>
+ </li>
+ <li>
+ <a href="/dev-doc/analysis/">Analysis</a>
+ </li>
+ <li>
+ <a href="/dev-doc/design/">Design</a>
+ </li>
+ <li>
+ <a href="/dev-doc/coding-standards.html">Coding Standards</a>
+ </li>
+ <li>
+ <a href="/dev-doc/release-guide.html">Release Guide</a>
+ </li>
+ <li>
+ <a href="/dev-doc/writing-tests.html">Writing unit/integration
tests</a>
+ </li>
+ <li>
+ <a href="/dev-doc/adding-custom-artifact-types.html">Adding custom
artifact types</a>
+ </li>
+ <li>
+ <a href="/dev-doc/configuring-relay-servers.html">Configuring and
using relay servers</a>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Get Involved <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="/get-involved/mailing-lists.html">Mailing Lists</a>
+ </li>
+ <li>
+ <a href="/get-involved/issue-tracking.html">Issue Tracking</a>
+ </li>
+ <li>
+ <a href="/get-involved/continuous-integration.html">Continuous
Integration</a>
+ </li>
+ <li>
+ <a href="/get-involved/source-code.html">Source Code</a>
+ </li>
+ <li>
+ <a href="/get-involved/project-team.html">Project Team</a>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Wiki <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a
href="https://cwiki.apache.org/confluence/display/ACE/Board+Reports";>Board
Reports <i class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a
href="https://cwiki.apache.org/confluence/display/ACE/Index";>Homepage <i
class="icon-share-alt"></i></a>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Apache <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="http://www.apache.org/";>Apache Homepage <i
class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="http://www.apache.org/licenses/";>Licenses <i
class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="http://www.apache.org/security/";>Security <i
class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship <i
class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="http://www.apache.org/foundation/thanks.html";>Thanks <i
class="icon-share-alt"></i></a>
+ </li>
+ </ul>
+ </li>
+</ul>
+
+ </div>
+ </div>
+ </div>
+ <div class="container">
+ <p><a href="/"><i class='icon-home'></i> Home</a> » <a
href="/docs/">Docs</a></p>
+ <h1>Coding Standards</h1>
+ <div class="clear"></div>
+ <div id="content"><p>This is a Java coding style guide for the Apache
ACE project.</p>
+<div class="toc">
+<ul>
+<li><a href="#summary">Summary</a></li>
+<li><a href="#class-layout-and-comments">Class layout and comments</a><ul>
+<li><a href="#files-and-filenames">Files and filenames</a><ul>
+<li><a href="#file-names">File names</a></li>
+<li><a href="#file-organization">File organization</a></li>
+<li><a href="#beginning-comments">Beginning comments</a><ul>
+<li><a href="#package-and-import-statements">Package and import
statements</a></li>
+<li><a href="#class-interface-enum-and-annotation-declarations">Class,
interface, enum and annotation declarations</a></li>
+<li><a href="#annotations">Annotations</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="#indentation">Indentation</a><ul>
+<li><a href="#line-length">Line length</a></li>
+<li><a href="#wrapping-lines">Wrapping lines</a></li>
+</ul>
+</li>
+<li><a href="#comment">Comment</a><ul>
+<li><a href="#comment-styles">Comment styles</a><ul>
+<li><a href="#single-line-comments">Single line comments</a></li>
+<li><a href="#block-comments">Block comments</a></li>
+<li><a href="#javadoc-comments">JavaDoc comments</a><ul>
+<li><a href="#html-tags">HTML tags</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="#java-syntax-and-its-layout">Java syntax and its layout</a><ul>
+<li><a href="#declarations">Declarations</a><ul>
+<li><a href="#number-per-line">Number per line</a></li>
+<li><a href="#placement">Placement</a></li>
+<li><a href="#initialization">Initialization</a></li>
+<li><a href="#class-and-interface-declarations">Class and Interface
Declarations</a></li>
+</ul>
+</li>
+<li><a href="#statements">Statements</a><ul>
+<li><a href="#simple-statements">Simple statements</a></li>
+<li><a href="#compound-statements">Compound statements</a></li>
+<li><a href="#if-if-else-if-else-if-else-statements">if, if-else, if else-if
else statements</a></li>
+<li><a href="#switch">switch</a></li>
+<li><a href="#try-catch">try - catch</a></li>
+<li><a href="#for-loops">for loops</a></li>
+</ul>
+</li>
+<li><a href="#white-space">White Space</a><ul>
+<li><a href="#blank-lines">Blank lines</a></li>
+<li><a href="#blank-spaces">Blank spaces</a></li>
+</ul>
+</li>
+<li><a href="#namingconventions">Naming conventions</a></li>
+</ul>
+</li>
+<li><a href="#downloads">Downloads</a></li>
+<li><a href="#references">References</a></li>
+</ul>
+</div>
+<h2 id="summary">Summary</h2>
+<p>This style guide is intended to help the computer professional produce
better Java programs. It presents a set of specific guidelines for using the
features of Java in a disciplined manner. The goal is to develop high quality,
reliable, reusable, portable software. For a number of reasons, no programming
language can ensure the achievements of these desirable objectives on its own.
Programming must be embedded in a disciplined development process that
addresses a number of topics in a well managed way. The use of Java is one of
those. It must conform to good programming practice based on well established
software engineering principles. This style guide is intended to bridge the gap
between these principles and the actual practice of programming in Java.</p>
+<p>Clear, readable, understandable source text eases program evolution,
adaptation and maintenance. First, such source text is more likely to be
correct and reliable. Second, effective code adaptation is a prerequisite to
code reuse, a technique that has the potential for drastic reductions in system
development costs. Easy adaptation requires thorough understanding of the
software, and that is facilitated considerably by clarity. Finally, since
maintenance (really evolution) is a costly process that continues throughout
the life of a system, clarity plays a major role in keeping maintenance costs
down. Over the entire life cycle, code has to be read and understood far more
often than it is written; the investment of effort in writing readable,
understandable code is thus well worthwhile. Many of the guidelines in this
style guide are designed to promote clarity of the source text.</p>
+<p>This style guide is intended for those involved in the development of real
software systems written in Java. Different roles in a software project can
exploit the style guide in different ways. The programmer can use it as a
reference on good Java style. It can be used in code reviews as a common
reference. Finally, lessons learned in real projects can be captured by
extending the style guide.</p>
+<h2 id="class-layout-and-comments">Class layout and comments</h2>
+<p>This chapter describes the layout for classes, interfaces, enums and
annotations. These all share a set of common properties, so they will be
described together and for readability all called 'classes' here.</p>
+<h3 id="files-and-filenames">Files and filenames</h3>
+<p>Files longer than 2000 lines are cumbersome and should be avoided.</p>
+<h4 id="file-names">File names</h4>
+<p>The file must be named after the class it represents. As for most cases
each file contains only one class, this is an easy naming convention. For
nested or inner classes the name of the main class must be the name of the
file. As names in Java are case-sensitive, the filename is case-sensitive
also.</p>
+<h4 id="file-organization">File organization</h4>
+<p>Each Java source file contains a single class or interface. Of course, this
excludes inner classes as these must be defined without an (outer) class, and
thus in the same file.</p>
+<p>Java source files have the following ordering:</p>
+<ul>
+<li>beginning comments;</li>
+<li>package and import statements;</li>
+<li>class and interface declarations.</li>
+</ul>
+<h4 id="beginning-comments">Beginning comments</h4>
+<p>Beginning comments are used for licensing and copyright information only.
Here at Apache, we embed the ASL 2.0 headers at the top of every file. Note
that they are not according to the JavaDoc style (See: How to write doc
comments for JavaDoc - Sun Microsystems, Inc.).</p>
+<h5 id="package-and-import-statements">Package and import statements</h5>
+<p>The first non-comment line of most Java source files is a package
statement. After an empty line import statements can follow. For example:</p>
+<div class="codehilite"><pre><span class="kn">package</span> <span
class="n">org</span><span class="o">.</span><span class="na">apache</span><span
class="o">.</span><span class="na">ace</span><span class="o">.</span><span
class="na">core</span><span class="o">.</span><span class="na">ui</span><span
class="o">;</span>
+
+<span class="kn">import</span> <span class="nn">java.awt.Frame</span><span
class="o">;</span>
+<span class="kn">import</span> <span
class="nn">java.io.InputStream</span><span class="o">;</span>
+</pre></div>
+
+
+<p>A few notes must be made here:</p>
+<ol>
+<li><em>Package rules.</em> When not using an explicit package statement in
your code the code still is in a package, the default package. This easily
results in name clashes and as package naming should be a part of the design,
always use an explicit package name. For naming rules of packages see <a
href="#namingconventions">naming conventions</a>;</li>
+<li><em>Import statements</em> need to be explicit in order to overcome name
clashes. They must be grouped by name;</li>
+<li><em>Import order.</em> First in this section should be the standard Java
imports like: java.lang.Throwable. Second should be the Java extensions (i.e.
javax), third, the third party stuff. Finally the project-specific imports
should be added.</li>
+</ol>
+<h5 id="class-interface-enum-and-annotation-declarations">Class, interface,
enum and annotation declarations</h5>
+<p>The following comment block is an example for the comment that belongs to
the declaration of a class, interface, enum or annotation. The JavaDoc syntax
results in the following block:</p>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * Configuration manager. Manages the configuration of an
application. Has features</span>
+<span class="cm"> * to import and export whole configurations and notifies
components that need to</span>
+<span class="cm"> * receive settings.</span>
+<span class="cm"> */</span>
+</pre></div>
+
+
+<p>The following table describes the parts of a class, interface, enum or
annotation declaration, in the order that they should appear.</p>
+<table>
+<thead>
+<tr>
+<th>Part of declaration</th>
+<th>Notes</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>documentation</td>
+<td>According to comment block as shown above.</td>
+</tr>
+<tr>
+<td>class, interface, enum or annotation statement</td>
+<td></td>
+</tr>
+<tr>
+<td>(static) variables</td>
+<td>These should be grouped by functionality rather than by scope.</td>
+</tr>
+<tr>
+<td>instance variables</td>
+<td>These should be grouped by functionality rather than by scope.</td>
+</tr>
+<tr>
+<td>constructors</td>
+<td>Start with the default constructor if any.</td>
+</tr>
+<tr>
+<td>methods</td>
+<td>These methods should also be grouped by functionality rather than by scope
or accessibility. E.g. a private class method can be in between two public
instance methods. The goal is to make reading and understanding the code
easier. When implementing an interface, group the methods that are part of the
interface.</td>
+</tr>
+<tr>
+<td>inner classes</td>
+<td>Are placed at the bottom of the file.</td>
+</tr>
+</tbody>
+</table>
+<h5 id="annotations">Annotations</h5>
+<p>Annotations for classes and methods should be done on the line directly
above the class or method. They should be indented to the same level. An
example:</p>
+<div class="codehilite"><pre><span class="nd">@Manageable</span><span
class="o">(</span><span class="n">description</span> <span class="o">=</span>
<span class="s">"Starts the system."</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kt">void</span> <span
class="nf">start</span><span class="o">()</span> <span class="o">{</span>
+ <span class="c1">// ...</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Annotations for parameters can be inlined like this:</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span
class="kt">void</span> <span class="nf">setValue</span><span
class="o">(</span><span class="nd">@Validation</span><span
class="o">(</span><span class="s">"x > 0 && x <
10"</span><span class="o">,</span> <span class="s">"Should be between
0 and 10."</span><span class="o">)</span> <span class="kt">int</span>
<span class="n">x</span><span class="o">)</span> <span class="o">{</span>
+ <span class="c1">// ...</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h3 id="indentation">Indentation</h3>
+<p>Four spaces should be used as unit of indentation. Use spaces or let your
editor convert tabs to spaces as some editors might show the tabs different
than they were intended! Tabs <em>must</em> be set <em>exactly</em> every 4
spaces.</p>
+<h4 id="line-length">Line length</h4>
+<p>There is no explicit limit for the length of a line. Make sure that the
flow of the code is clear and that, when printing the file, it is well formed
when using a reasonable font.</p>
+<h4 id="wrapping-lines">Wrapping lines</h4>
+<p>When an expression will not fit on a single line, break it according to
these general principles:</p>
+<ul>
+<li>break after a comma;</li>
+<li>break before an operator;</li>
+<li>prefer higher level breaks to lower level breaks;</li>
+<li>indent the new line with a tab;</li>
+<li>if the above rules lead to confusing code or to code that's squished up
against the right margin, please use common sense.</li>
+</ul>
+<h3 id="comment">Comment</h3>
+<h4 id="comment-styles">Comment styles</h4>
+<p>The Java language supports three different kinds of comments:</p>
+<ol>
+<li>single line comments;</li>
+<li>block comments;</li>
+<li>JavaDoc comments.</li>
+</ol>
+<h5 id="single-line-comments">Single line comments</h5>
+<p>The compiler ignores everything from <code>//</code> to the end of the
line. Use this style when adding a description or some kind of explanation on
the same line of code or the line above.</p>
+<div class="codehilite"><pre><span class="kt">int</span> <span
class="n">a</span><span class="o">;</span> <span class="c1">// acceleration of
the car</span>
+
+<span class="c1">// all names that should be searched</span>
+<span class="n">String</span><span class="o">[]</span> <span
class="n">names</span><span class="o">;</span>
+</pre></div>
+
+
+<h5 id="block-comments">Block comments</h5>
+<p>The compiler ignores everything from <code>/*</code> to <code>*/</code>.
Use this style for internal comments and copyright headers.</p>
+<div class="codehilite"><pre><span class="cm">/*</span>
+<span class="cm"> * This code is Copyright (c) 2012 Apache Software
Foundation. All rights reserved.</span>
+<span class="cm"> * You are not allowed to remember or reproduce anything you
read below.</span>
+<span class="cm"> */</span>
+</pre></div>
+
+
+<h5 id="javadoc-comments">JavaDoc comments</h5>
+<p>This indicates a documentation comment (doc comment, for short). The
compiler ignores this kind of comment, just like it ignores comments that use
<code>/*</code> and <code>*/</code>. The JavaDoc tool uses doc comments when
preparing automatically generated documentation (See: JavaDoc keywords and HTML
tags). Note that JavaDoc only uses this documentation when it occurs at an
expected position in the file like the class definition or a member
declaration. </p>
+<p>These comments are used to provide English descriptions of the classes,
interfaces, enums, annotations, methods and the description of data structures
and algorithms. These comments should be used at the beginning of each class
and before each method. The official JavaDoc guidelines (see references at the
end of this document) should be followed, as they provide a good and clear
writing style.</p>
+<p>A method block comment looks as follows:</p>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * Position the splitter location at a specified
position.</span>
+<span class="cm"> * This method can for instance be used when the last
position</span>
+<span class="cm"> * is stored as a preference setting for the user.</span>
+<span class="cm"> *</span>
+<span class="cm"> * @param position New position of divider, defined in
pixels</span>
+<span class="cm"> * from the left of the containing window.</span>
+<span class="cm"> * @exception
org.apache.ace.units.si.exceptions.PositionException Whenever</span>
+<span class="cm"> * an invalid position is passed.</span>
+<span class="cm"> * @see com.sun.java.swing.JSplitPane</span>
+<span class="cm"> */</span>
+<span class="kd">public</span> <span class="kt">void</span> <span
class="nf">setSplitterLocation</span><span class="o">(</span><span
class="kt">int</span> <span class="n">position</span><span class="o">)</span>
<span class="kd">throws</span> <span class="n">PositionException</span> <span
class="o">{</span>
+</pre></div>
+
+
+<h6 id="html-tags">HTML tags</h6>
+<p>For class headers, method headers and member variables JavaDoc is used in
order to generate API documentation. Some HTML-tags that can be used in order
to make the comment blocks more readable:</p>
+<table>
+<thead>
+<tr>
+<th>Tag</th>
+<th>Short description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code><p></code></td>
+<td>New paragraph.</td>
+</tr>
+<tr>
+<td><code><br></code></td>
+<td>Break, a carriage return. For separation of two paragraphs, usage of
<code><p></code> is preferred.</td>
+</tr>
+<tr>
+<td><code><ul><li></li></ul></code></td>
+<td>Unordered list of items. Each item should start with a
<code><li></code> tag. Most browsers format this as a bullet list.</td>
+</tr>
+<tr>
+<td><code><code></code></code></td>
+<td>Code samples. Use this when refering to class names, method names,
parameter names, etc.</td>
+</tr>
+</tbody>
+</table>
+<p>There is no need to embed the parameter name in the <code>@param</code> tag
in <code><code></code> tags; this is done by JavaDoc automatically. The
same holds for the exception name in the <code>@exception</code> or
<code>@throws</code> tag. In the clarifying text however, use the
<code><code></code> tags when refering to parameter names etc. The
example below shows the <code><code></code> tag being used for the array
parameter in the text, but not in its definition.</p>
+<p>Example:</p>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * Prints a range from an object array. The range</span>
+<span class="cm"> * is specified by the first element to print, and</span>
+<span class="cm"> * ranges to the last element of the array.</span>
+<span class="cm"> *</span>
+<span class="cm"> * @param list contains the objects to print</span>
+<span class="cm"> * @param first index of first element in </span>
+<span class="cm"> * the <code>list</code> to print</span>
+<span class="cm"> */</span>
+<span class="kd">public</span> <span class="kt">void</span> <span
class="nf">printRange</span><span class="o">(</span><span
class="n">List</span><span class="o"><</span><span
class="n">Printable</span><span class="o">></span> <span
class="n">list</span><span class="o">,</span> <span class="kt">int</span> <span
class="n">first</span><span class="o">)</span> <span class="o">{</span>
+</pre></div>
+
+
+<h2 id="java-syntax-and-its-layout">Java syntax and its layout</h2>
+<h3 id="declarations">Declarations</h3>
+<p>When declaring a variable or method make the accessibility as restrictive
as possible. When using multiple keywords use the following ordering of
keywords:</p>
+<ol>
+<li><em>accessibility</em> - Start with the accessibility as it makes clear if
the method or variable is reachable at all;</li>
+<li><em>static</em> (if applicable);</li>
+<li><em>final</em> (if applicable);</li>
+<li><em>return type</em> (methods only) or type (for variables) - For
readability, the type is as close to the name as possible.</li>
+</ol>
+<p>This order is also compatible with the order that is used in Java for the
main() method. This results in following sequence:</p>
+<div class="codehilite"><pre><span class="c1">// A familiar one:</span>
+<span class="kd">public</span> <span class="kd">static</span> <span
class="kt">void</span> <span class="nf">main</span><span
class="o">(</span><span class="n">String</span><span class="o">[]</span> <span
class="n">args</span><span class="o">)</span> <span class="o">{}</span>
+<span class="kd">private</span> <span class="kd">static</span> <span
class="n">String</span> <span class="n">m_lastCreated</span> <span
class="o">=</span> <span class="kc">null</span><span class="o">;</span>
+<span class="kd">private</span> <span class="kd">static</span> <span
class="kd">final</span> <span class="kt">int</span> <span class="n">RED</span>
<span class="o">=</span> <span class="mi">4711</span><span class="o">;</span>
+</pre></div>
+
+
+<h4 id="number-per-line">Number per line</h4>
+<p>One declaration per line is recommended since it encourages commenting and
it does not lead to confusing code. It also is more clear about the explicit
initialization of variables as discussed in Initialization.</p>
+<p>Example:</p>
+<div class="codehilite"><pre><span class="kt">int</span> <span
class="n">level</span> <span class="o">=</span> <span class="mi">0</span><span
class="o">;</span> <span class="c1">// level where user enters the system</span>
+<span class="kt">int</span> <span class="n">horizontalSize</span> <span
class="o">=</span> <span class="mi">0</span><span class="o">;</span> <span
class="c1">// horizontal size of current level layer</span>
+</pre></div>
+
+
+<p>is preferred over:</p>
+<div class="codehilite"><pre><span class="kt">int</span> <span
class="n">level</span><span class="o">,</span> <span
class="n">horizontalSize</span><span class="o">;</span> <span class="c1">//
level and size of current level layer</span>
+</pre></div>
+
+
+<h4 id="placement">Placement</h4>
+<p>In a method, declare local variables just before they are needed. This
overcomes the problem of a big list of parameters at the beginning of a method
and the use of a variable becomes more clearly in the context of the code, e.g.
its initialization.</p>
+<h4 id="initialization">Initialization</h4>
+<p>The initialization of class variables is strictly not necessary because of
the default initialization that takes place for these kinds of members. For
some types, e.g. Booleans, this requires detailed knowledge of all the default
values so it is more clear and explicit to initialize each member. </p>
+<p>Variables that are used and declared within methods must always be
initialized explicitly (the compiler will generate an error when you forget
this).</p>
+<h4 id="class-and-interface-declarations">Class and Interface Declarations</h4>
+<p>When coding Java classes and interfaces, the following formatting rules
should be followed:</p>
+<ul>
+<li>no space between a method and its parameter list;</li>
+<li><code>{</code> appears at the end of the same line as the declaration;</li>
+<li><code>}</code> starts a line by itself indented to match its corresponding
opening statement, except when it is a null statement, in which the case the
<code>}</code> should appear immediately after the <code>{</code>.</li>
+</ul>
+<p>Example:</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">class</span> <span class="nc">DefaultStrategy</span> <span
class="kd">extends</span> <span class="n">Strategy</span> <span
class="o">{</span>
+ <span class="kd">private</span> <span class="kt">int</span> <span
class="n">m_attempts</span> <span class="o">=</span> <span
class="mi">0</span><span class="o">;</span>
+
+ <span class="kd">public</span> <span
class="nf">DefaultStrategy</span><span class="o">(</span><span
class="kt">int</span> <span class="n">attempts</span><span class="o">)</span>
<span class="o">{</span>
+ <span class="kd">super</span><span class="o">();</span>
+ <span class="n">m_attempts</span> <span class="o">=</span> <span
class="n">attempts</span><span class="o">;</span>
+ <span class="o">}</span>
+
+ <span class="kt">void</span> <span class="nf">execute</span><span
class="o">()</span> <span class="o">{}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h3 id="statements">Statements</h3>
+<h4 id="simple-statements">Simple statements</h4>
+<p>Each line should contain at most one statement.</p>
+<h4 id="compound-statements">Compound statements</h4>
+<p>Compound statements are statements that contain lists of statements
enclosed in braces ("{...}"):</p>
+<ul>
+<li>The enclosed statements should be indented one more level than the
compound statement;</li>
+<li>The opening brace should be at the end of the line that begins the
compound statement; the closing brace should begin a line and be indented to
the beginning of the compound statement;</li>
+<li>Braces are used around all statements, even single statements, when they
are part of a control structure, such as a if-else or for statement. This makes
it easier to add statements without accidentally introducing bugs due to
forgetting to add braces.</li>
+</ul>
+<h4 id="if-if-else-if-else-if-else-statements">if, if-else, if else-if else
statements</h4>
+<p>There are a lot of nested possibilities for if-else constructions. All
these variations can be programmed in very cryptic ways that easily and often
will lead to buggy code. By being more explicit in the used coding style a lot
of confusion can be taken away.</p>
+<blockquote>
+<p>When using only one statement in a compound block brackets are optional. It
is good practice, and therefore required, to always use brackets because
mistakes can be made easily when adding a second statement and brackets are
forgotten.</p>
+</blockquote>
+<p>The following example illustrates the correct use of brackets in a few
different if-then-else constructions:</p>
+<div class="codehilite"><pre><span class="k">if</span> <span
class="o">(</span><span class="n">condition</span><span class="o">)</span>
<span class="o">{</span>
+ <span class="n">statement1</span><span class="o">;</span>
+ <span class="n">statement2</span><span class="o">;</span>
+<span class="o">}</span>
+<span class="k">else</span> <span class="o">{</span>
+ <span class="n">statement3</span><span class="o">;</span>
+<span class="o">}</span>
+
+<span class="k">if</span> <span class="o">(</span><span
class="n">condition</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">statement1</span><span class="o">;</span>
+ <span class="n">statement2</span><span class="o">;</span>
+<span class="o">}</span>
+<span class="k">else</span> <span class="nf">if</span> <span
class="o">(</span><span class="n">condition1</span><span class="o">)</span>
<span class="o">{</span>
+ <span class="n">statement3</span><span class="o">;</span>
+ <span class="n">statement4</span><span class="o">;</span>
+<span class="o">}</span>
+<span class="k">else</span> <span class="o">{</span>
+ <span class="n">statement5</span><span class="o">;</span>
+ <span class="n">statement6</span><span class="o">;</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Note that in the example the else if construction is started at a new line
so the statement can not be overlooked.</p>
+<h4 id="switch">switch</h4>
+<p>When using a switch statement use following guidelines:</p>
+<ul>
+<li>Consider including a default case, unless it would do nothing. The break
in the default case is redundant, but it prevents a fall-through error if later
another case is added;</li>
+<li>The so-called fall-through construction should be avoided. Only when there
are good reasons to use it, make sure that it is very clear that a fall-through
is used (comment it).</li>
+</ul>
+<p>The next example shows the sample code that uses the guidelines for a
switch statement:</p>
+<div class="codehilite"><pre><span class="k">switch</span> <span
class="o">(</span><span class="n">condition</span><span class="o">)</span>
<span class="o">{</span>
+ <span class="k">case</span> <span class="nl">A:</span>
+ <span class="n">statements</span><span class="o">;</span>
+ <span class="c1">// falls through here, because...</span>
+ <span class="k">case</span> <span class="nl">B:</span>
+ <span class="n">statements</span><span class="o">;</span>
+ <span class="k">break</span><span class="o">;</span>
+ <span class="k">default</span><span class="o">:</span>
+ <span class="n">statements</span><span class="o">;</span>
+ <span class="k">break</span><span class="o">;</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h4 id="try-catch">try - catch</h4>
+<p>A try - catch statement should have the following format:</p>
+<div class="codehilite"><pre><span class="k">try</span> <span
class="o">{</span>
+ <span class="n">statements</span><span class="o">;</span>
+<span class="o">}</span>
+<span class="k">catch</span> <span class="o">(</span><span
class="n">ExceptionClass</span> <span class="n">e</span><span
class="o">)</span> <span class="o">{</span>
+ <span class="n">statements</span><span class="o">;</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>When using finally to add code that always will be executed this will look
like:</p>
+<div class="codehilite"><pre><span class="k">try</span> <span
class="o">{</span>
+ <span class="n">statements</span><span class="o">;</span>
+<span class="o">}</span>
+<span class="k">catch</span> <span class="o">(</span><span
class="n">ExceptionClass</span> <span class="n">e</span><span
class="o">)</span> <span class="o">{</span>
+ <span class="n">statements</span><span class="o">;</span>
+<span class="o">}</span>
+<span class="k">finally</span> <span class="o">{</span>
+ <span class="n">statements</span><span class="o">;</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Note that the catch and the finally start at a new line in order to be
compliant to the guidelines for if-then-else statements.</p>
+<h4 id="for-loops">for loops</h4>
+<p>New style for loops are generally preferred over old style ones, unless you
explicitly need the index, or you have to make the code run on pre-Java 5
virtual machines.</p>
+<p>Old style, a good example that needs the index anyway:</p>
+<div class="codehilite"><pre><span class="c1">// lookup a value in a list,
return the index</span>
+<span class="n">List</span><span class="o"><</span><span
class="n">Element</span><span class="o">></span> <span
class="n">list</span><span class="o">;</span>
+<span class="k">for</span> <span class="o">(</span><span class="kt">int</span>
<span class="n">i</span> <span class="o">=</span> <span
class="mi">0</span><span class="o">;</span> <span class="n">i</span> <span
class="o"><</span> <span class="n">list</span><span class="o">.</span><span
class="na">size</span><span class="o">();</span> <span class="n">i</span><span
class="o">++)</span> <span class="o">{</span>
+ <span class="k">if</span> <span class="o">(</span><span
class="n">value</span><span class="o">.</span><span
class="na">equals</span><span class="o">(</span><span
class="n">list</span><span class="o">.</span><span class="na">get</span><span
class="o">(</span><span class="n">i</span><span class="o">))</span> <span
class="o">{</span>
+ <span class="k">return</span> <span class="n">index</span><span
class="o">;</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>New style, a good example that iterates over a list without any need for an
index or type casts:</p>
+<div class="codehilite"><pre><span class="c1">// iterate over a list, printing
all values</span>
+<span class="n">List</span><span class="o"><</span><span
class="n">Element</span><span class="o">></span> <span
class="n">list</span><span class="o">;</span>
+<span class="k">for</span> <span class="o">(</span><span
class="n">Element</span> <span class="n">e</span> <span class="o">:</span>
<span class="n">list</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">System</span><span class="o">.</span><span
class="na">out</span><span class="o">.</span><span
class="na">println</span><span class="o">(</span><span class="s">" -
"</span> <span class="o">+</span> <span class="n">e</span><span
class="o">);</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h3 id="white-space">White Space</h3>
+<h4 id="blank-lines">Blank lines</h4>
+<p>Blank lines improve readability by setting of sections of code that are
logically related. One blank line should always be used in the following
circumstances:</p>
+<ul>
+<li>between class and interface definitions;</li>
+<li>between methods;</li>
+<li>before a block or single line comment;</li>
+<li>between logical sections inside a method to improve readability.</li>
+</ul>
+<h4 id="blank-spaces">Blank spaces</h4>
+<p>Blank spaces should be used in the following circumstances:</p>
+<ul>
+<li>
+<p>A keyword followed by a parenthesis should be separated by a space:</p>
+<div class="codehilite"><pre><span class="k">while</span> <span
class="o">(</span><span class="n">index</span> <span class="o">></span>
<span class="mi">5</span><span class="o">)</span> <span class="o">{</span>
+ <span class="c1">// ...</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Note that blanks should not be used between a method call and its opening
parenthesis. This helps to distinguish keywords from function calls;</p>
+</li>
+<li>
+<p>Blanks should appear after commas in argument lists;</p>
+</li>
+<li>
+<p>All binary and ternary operators except "." should be separated from their
operands by spaces. Blanks should never separate unary operators such as unary
minus, increment("++") and decrement("--") from their operands:</p>
+<div class="codehilite"><pre><span class="n">a</span> <span
class="o">+=</span> <span class="n">c</span> <span class="o">+</span> <span
class="n">d</span><span class="o">;</span>
+<span class="n">a</span> <span class="o">=</span> <span
class="o">(</span><span class="n">a</span> <span class="o">+</span> <span
class="n">b</span><span class="o">)</span> <span class="o">/</span> <span
class="o">(</span><span class="n">c</span> <span class="o">*</span> <span
class="n">d</span><span class="o">);</span>
+<span class="n">a</span> <span class="o">=</span> <span
class="o">(</span><span class="n">b</span> <span class="o">></span> <span
class="n">c</span><span class="o">)</span> <span class="o">?</span> <span
class="n">b</span> <span class="o">:</span> <span class="n">c</span><span
class="o">;</span>
+<span class="n">xCoord</span><span class="o">--;</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>The expressions in a for statement should be separated by blanks:</p>
+<div class="codehilite"><pre><span class="k">for</span> <span
class="o">(</span><span class="n">expr1</span><span class="o">;</span> <span
class="n">cond1</span><span class="o">;</span> <span
class="n">expr2</span><span class="o">)</span> <span class="o">{</span>
+<span class="o">}</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>Casts should be followed by a blank:</p>
+<div class="codehilite"><pre><span class="n">myInstance</span><span
class="o">.</span><span class="na">doIt</span><span class="o">((</span><span
class="n">TreeFrame</span><span class="o">)</span> <span
class="n">frame</span><span class="o">);</span>
+</pre></div>
+
+
+</li>
+</ul>
+<h3 id="namingconventions">Naming conventions</h3>
+<p>Naming conventions make programs more understandable by making them easier
to read. They can also give information about the function of the
identifier.</p>
+<dl>
+<dt><strong>(inner) classes, interfaces, enums and annotations</strong></dt>
+<dd>Names should be nouns, in mixed case with the first letter of each word
capitalised. Try to keep your names simple and descriptive. Use whole words and
avoid acronyms and abbreviations.<br/>
+Examples:<br/>
+<code>class Raster</code><br/>
+<code>class TreeFrame</code></dd>
+<dt><strong>interfaces</strong></dt>
+<dd>Like class names, but if there is a name clash, the interface wins.<br/>
+Example:<br/>
+<code>interface RemoteRepository extends Repository</code></dd>
+<dt><strong>services</strong></dt>
+<dd>Same as interfaces, so don't append "Service" as you usually do not know
if an interface is a service or not.<br/>
+Example:<br/>
+<code>interface ConnectionFactory</code></dd>
+<dt><strong>implementation classes</strong></dt>
+<dd>If a class implements an interface, it should use the name of the
interface as part of its name, adding something specific for this
implementation to it, or <em>Impl</em> if that does not make sense.<br/>
+Examples:<br/>
+<code>class FileBasedRepository implements Repository</code><br/>
+<code>class VersionServlet implements HttpServlet</code></dd>
+<dt><strong>exceptions</strong></dt>
+<dd>Like class names; always ending in "Exception".<br/>
+Example:<br/>
+<code>InputException</code></dd>
+<dt><strong>methods</strong></dt>
+<dd>Methods should be verbs in mixed case with the first letter lowercase.
Within each method name capital letters separate words. Property methods or
get-set methods are used as follows:
+When a method is used to get a value start the method name with 'get'. When a
method is used to set a value start the method name with 'set'. When a method
returns a boolean start the method name with 'is'.<br/>
+Examples:<br/>
+<code>run();</code><br/>
+<code>runFast();</code><br/>
+<code>setBackground();</code><br/>
+<code>isOptional();</code></dd>
+<dt><strong>variables (except for (constant) static final variables and member
variables)</strong></dt>
+<dd>All variables are in mixed case with a lowercase first letter. Words are
separated by capital letters.<br/>
+Examples:<br/>
+<code>int index;</code><br/>
+<code>float myWidth;</code></dd>
+<dt><strong>member variables</strong></dt>
+<dd>The same capitalisation as for normal variables prefixed with 'm_'.<br/>
+Examples:<br/>
+<code>int m_index;</code><br/>
+<code>float m_myWidth;</code></dd>
+<dt><strong>constant (static final) variables, enum names</strong></dt>
+<dd>Names should be all uppercase with words separated by underscores
('_').<br/>
+Example:<br/>
+<code>public static final int MAX_LIMIT = 99;</code></dd>
+<dt><strong>packages</strong></dt>
+<dd>Lowercase only; avoid lengthy package names; always start with
<em>org.apache.ace</em>.<br/>
+Example:<br/>
+<code>package org.apache.ace.demo.bundle;</code></dd>
+</dl>
+<h2 id="downloads">Downloads</h2>
+<p>For various coding style checkers and IDE's we have configuration files
that support this style guide. You can download them from the list below:</p>
+<ul>
+<li><a
href="http://svn.apache.org/repos/asf/ace/trunk/etc/style-guide/checkstyle/";>Checkstyle
configuration</a></li>
+</ul>
+<h2 id="references">References</h2>
+<ul>
+<li>Java Code Conventions - Sun Microsystems, Inc., <a
href="http://java.sun.com/docs/codeconv/";>http://java.sun.com/docs/codeconv/</a>;</li>
+<li>How to Write Doc Comments for JavaDoc - Sun Microsystems, Inc., <a
href="http://java.sun.com/j2se/javadoc/writingdoccomments/";>http://java.sun.com/j2se/javadoc/writingdoccomments/</a>;</li>
+<li>JavaDoc homepage - Sun Microsystems, Inc., <a
href="http://java.sun.com/j2se/javadoc/";>http://java.sun.com/j2se/javadoc/</a>.</li>
+</ul></div>
+ <hr>
+ <footer>
+ <p>Copyright © 2012-2014 <a href="http://www.apache.org/";>The
Apache Software Foundation</a>, Licensed under the <a
href="http://www.apache.org/licenses/LICENSE-2.0";>Apache License, Version
2.0</a>.<br/>Apache ACE, the Apache ACE logo, Apache and the Apache feather
logo are trademarks of The Apache Software Foundation. All other marks
mentioned may be trademarks or registered trademarks of their respective
owners.</p>
+ </footer>
+ </div>
+ </body>
+</html>
Added: websites/staging/ace/trunk/content/docs/configuring-relay-servers.html
==============================================================================
--- websites/staging/ace/trunk/content/docs/configuring-relay-servers.html
(added)
+++ websites/staging/ace/trunk/content/docs/configuring-relay-servers.html Mon
Nov 24 22:42:13 2014
@@ -0,0 +1,409 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+ <head>
+ <title>Configuring and using ACE relay servers</title>
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ <meta property="og:image" content="//www.apache.org/images/asf_logo.gif" />
+ <link href="/css/bootstrap.min.css" rel="stylesheet" media="screen">
+ <link href="/css/prettify.css" rel="stylesheet" media="screen">
+ <link href="/css/code.css" rel="stylesheet" media="screen">
+ <script src="//code.jquery.com/jquery.js"></script>
+ <script src="/js/bootstrap.min.js"></script>
+ <script src="/js/prettify.js"></script>
+
+
+
+ <script>
+ $(function () { prettyPrint() })
+ $().dropdown()
+ </script>
+ </head>
+ <body style="padding-top: 50px;">
+ <div class="navbar navbar-fixed-top navbar-inverse">
+ <div class="navbar-inner">
+ <div class="container">
+ <a class="brand" href="/index.html">Apache ACE™</a>
+ <ul class="nav">
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">News <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="/news.html">News</a>
+ </li>
+ <li>
+ <a href="/on-the-web.html">On the web</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="/downloads.html">Downloads</a>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Users <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="/user-doc/introduction.html">Introduction</a>
+ </li>
+ <li>
+ <a href="/user-doc/getting-started.html">Getting Started</a>
+ </li>
+ <li>
+ <a href="/user-doc/user-guide.html">User Guide</a>
+ </li>
+ <li>
+ <a href="/user-doc/features.html">Features</a>
+ </li>
+ <li>
+ <a href="/user-doc/shellapi.html">Client Shell API</a>
+ </li>
+ <li>
+ <a href="/user-doc/restapi.html">Client REST API</a>
+ </li>
+ <li>
+ <a href="/user-doc/useradmin-ui.html">User Management Guide</a>
+ </li>
+ <li>
+ <a href="/user-doc/faq.html">FAQ</a>
+ </li>
+ <li>
+ <a href="/user-doc/support.html">Support</a>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Developers <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="/dev-doc/getting-started.html">Getting Started</a>
+ </li>
+ <li>
+ <a href="/dev-doc/requirements/">Requirements</a>
+ </li>
+ <li>
+ <a href="/dev-doc/architecture.html">Architecture</a>
+ </li>
+ <li>
+ <a href="/dev-doc/analysis/">Analysis</a>
+ </li>
+ <li>
+ <a href="/dev-doc/design/">Design</a>
+ </li>
+ <li>
+ <a href="/dev-doc/coding-standards.html">Coding Standards</a>
+ </li>
+ <li>
+ <a href="/dev-doc/release-guide.html">Release Guide</a>
+ </li>
+ <li>
+ <a href="/dev-doc/writing-tests.html">Writing unit/integration
tests</a>
+ </li>
+ <li>
+ <a href="/dev-doc/adding-custom-artifact-types.html">Adding custom
artifact types</a>
+ </li>
+ <li>
+ <a href="/dev-doc/configuring-relay-servers.html">Configuring and
using relay servers</a>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Get Involved <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="/get-involved/mailing-lists.html">Mailing Lists</a>
+ </li>
+ <li>
+ <a href="/get-involved/issue-tracking.html">Issue Tracking</a>
+ </li>
+ <li>
+ <a href="/get-involved/continuous-integration.html">Continuous
Integration</a>
+ </li>
+ <li>
+ <a href="/get-involved/source-code.html">Source Code</a>
+ </li>
+ <li>
+ <a href="/get-involved/project-team.html">Project Team</a>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Wiki <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a
href="https://cwiki.apache.org/confluence/display/ACE/Board+Reports";>Board
Reports <i class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a
href="https://cwiki.apache.org/confluence/display/ACE/Index";>Homepage <i
class="icon-share-alt"></i></a>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Apache <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="http://www.apache.org/";>Apache Homepage <i
class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="http://www.apache.org/licenses/";>Licenses <i
class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="http://www.apache.org/security/";>Security <i
class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship <i
class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="http://www.apache.org/foundation/thanks.html";>Thanks <i
class="icon-share-alt"></i></a>
+ </li>
+ </ul>
+ </li>
+</ul>
+
+ </div>
+ </div>
+ </div>
+ <div class="container">
+ <p><a href="/"><i class='icon-home'></i> Home</a> » <a
href="/docs/">Docs</a></p>
+ <h1>Configuring and using ACE relay servers</h1>
+ <div class="clear"></div>
+ <div id="content"><p>When using Apache ACE in a large deployment
scenario, in which many targets need to be
+provisioned, it might be necessary to scale the number of servers with
additional relay
+servers. How many targets can be handled by a single server depends a bit on
the number of
+changes that are made to the metadata, and how often each target contacts the
ACE server
+to get the latest changes. Just to give an impression of what Apache ACE can
handle, we
+tested a single ACE server, during the development of ACE, with several
hundred of
+targets, which caused not real problems apart from a significant load on your
disk and
+CPUs. If you come into a situation in which a single ACE server is not able to
cope with
+the load of your targets, or you want to replicate your metadata across
several servers to
+achieve better availability, you can use this document to set up and configure
relay
+servers.</p>
+<div class="toc">
+<ul>
+<li><a href="#overview">Overview</a></li>
+<li><a href="#log-synchronisation-between-target-and-relay">Log
synchronisation between target and relay</a></li>
+<li><a href="#log-synchronisation-between-relay-and-main-server">Log
synchronisation between relay and main server</a></li>
+<li><a href="#deployment-provider">Deployment provider</a></li>
+<li><a href="#deployment-servlet">Deployment servlet</a></li>
+<li><a href="#task-scheduler">Task scheduler</a></li>
+<li><a href="#target-configuration">Target configuration</a></li>
+<li><a href="#notes">Notes</a></li>
+</ul>
+</div>
+<h2 id="overview">Overview</h2>
+<p>In ACE, each target only talks to a single ACE server at a time. From this
perspective, an
+ACE server only serves two major tasks: </p>
+<ol>
+<li>receiving and storing log information from targets, and;</li>
+<li>providing deployment packages containing software updates.</li>
+</ol>
+<p id="fig1">In situations where lots of targets need to be provisioned with
software, having only a
+single ACE server can impose major scalability and availability issues. To
solve this, ACE
+can be set up to act as relay server for an upstream (or master) ACE server.
This allows a
+tree-topology of ACE servers to be created that can distribute the load of
many targets
+evenly, as denoted in the following image:</p>
+<p><img alt="Figure 1: ACE server topology"
src="/docs/ace_server_topology.png" title="Figure 1: An example server
topology, showing multiple servers relaying information from an upstream
server." /><br />
+<strong>Figure 1</strong>: An example server topology, showing multiple
servers relaying information from an upstream server. Many other topologies are
possible as well.</p>
+<p>Note that target logs need to be propagated to the main ACE server in order
to make this
+information available for further inspection. For example, a target operator
might want to
+know the current status of a target, even if this target is not directly
served by the
+main ACE server. </p>
+<p id="fig2">An ACE relay server is a stripped down ACE server that only
includes the bare minimum
+functionality to serve its targets. In addition to accepting log-updates from
targets and
+provisioning software updates to its targets, it relays log information it
received from
+its targets to the upstream ACE server and replicates (at least) the
<tt>deployment</tt>
+repository from the upstream ACE server for its own use. A schematic overview
of the
+functional blocks in a relay server is shown in figure 2:</p>
+<p><img alt="Figure 2: Functional overview relay server"
src="/docs/relay_functional_overview.png" title="Figure 2: A functional
overview of how a relay server functions." /><br />
+<strong>Figure 2</strong>: A functional overview of how a relay server
functions.</p>
+<p>In the following sections, each of these functional blocks will be
explained in more depth
+along with how to configure them. The configuration examples are shown as
simple key-value
+pairs separated with an equals (<tt>=</tt>) sign. Lines starting with a hash
(<tt>#</tt>)
+are considered comments. </p>
+<h2 id="log-synchronisation-between-target-and-relay">Log synchronisation
between target and relay</h2>
+<p>Like in a single-server scenario, the relay must allow a target to upload
its log before
+it can be synchronised with the main ACE server.</p>
+<p>To configure the storage of logs from targets on the relay server, we need
to instantiate
+a log store by supplying the following configuration to the
+<tt>org.apache.ace.log.server.store.factory</tt> managed service factory:</p>
+<div class="codehilite"><pre><span class="c"># a symbolic name used to
reference to this store from other services</span>
+<span class="na">name</span><span class="o">=</span><span
class="s">auditlog</span>
+</pre></div>
+
+
+<p>This will instantiate a new log store service named <tt>auditlog</tt><sup
id="fnref:1"><a class="footnote-ref" href="#fn:1" rel="footnote">1</a></sup>
that can be used
+to store the log information of targets.</p>
+<p>To allow targets to upload their logs to the relay server, a log-servlet
needs to be
+instantiated. This is done by supplying the following configuration to the
+<tt>org.apache.ace.log.server.servlet.factory</tt> managed service factory:</p>
+<div class="codehilite"><pre><span class="c"># the symbolic name of the actual
log store to store the uploaded logs in</span>
+<span class="na">name</span><span class="o">=</span><span
class="s">auditlog</span>
+<span class="c"># the alias/endpoint at which the servlet is registered</span>
+<span class="na">org.apache.ace.server.servlet.endpoint</span><span
class="o">=</span><span class="s">/auditlog</span>
+<span class="c"># whether or not to use authentication</span>
+<span class="na">authentication.enabled</span><span class="o">=</span><span
class="s">false</span>
+</pre></div>
+
+
+<p>This will instantiate a servlet that listens on the <tt>/auditlog</tt><sup
id="fnref:2"><a class="footnote-ref" href="#fn:2" rel="footnote">2</a></sup>
endpoint (for
+example, <tt>http://my.relay.server:8080/auditlog</tt>). The given
<tt>name</tt>
+configuration key is used to lookup the actual log store we've created
previously.</p>
+<h2 id="log-synchronisation-between-relay-and-main-server">Log synchronisation
between relay and main server</h2>
+<p>With the log store and servlet configured and in place, a target is now
able to
+synchronise its logs with the relay server. However, once uploaded to the
relay server,
+the logs will not propagate automatically to the main ACE server. A separate
+log-synchronisation task is responsible for this. To enable this task, we need
to supply
+the following configuration to the
<tt>org.apache.ace.log.server.task.factory</tt> managed
+service factory:</p>
+<div class="codehilite"><pre><span class="c"># the symbolic name of the actual
log store to synchronise</span>
+<span class="na">name</span><span class="o">=</span><span
class="s">auditlog</span>
+<span class="c"># how to synchronise logs, can be 'pull',
'push' or 'pushpull'</span>
+<span class="na">mode</span><span class="o">=</span><span class="s">push</span>
+</pre></div>
+
+
+<p>This will create a "task" service that will push all log information from
the
+<tt>auditlog</tt><sup id="fnref:1"><a class="footnote-ref" href="#fn:1"
rel="footnote">1</a></sup> store to the main server. The <tt>mode</tt>
configuration key
+denotes how to synchronise with the main server:</p>
+<ul>
+<li><tt>push</tt> synchronises (or "pushes") the logs from the relay server to
the main server and is typically used in a relaying situation as described in
this document;</li>
+<li><tt>pull</tt> synchronises (or "pulls") the logs from the main server to
the relay server and is typically used to create secondary backup servers and
is not further discussed in this document;</li>
+<li><tt>pushpull</tt> will perform a two-way synchronisation between relay and
main server and can be used to support fail-over situations.</li>
+</ul>
+<p>In addition, the log synchronisation task (and other tasks as well, see
below) needs to
+know what upstream server it should synchronise with. For this information, it
uses the
+ACE discovery service, which is configured by supplying, for example, the
following
+configuration to the <tt>org.apache.discovery.property</tt><sup
id="fnref:3"><a class="footnote-ref" href="#fn:3" rel="footnote">3</a></sup>
managed service:</p>
+<div class="codehilite"><pre><span class="c"># what is the URL to the *main*
ACE server</span>
+<span class="na">serverURL</span> <span class="o">=</span> <span
class="s">http://my.main.server:8080</span>
+</pre></div>
+
+
+<h2 id="deployment-provider">Deployment provider</h2>
+<p>The relay needs to have at least a deployment repository<sup
id="fnref:4"><a class="footnote-ref" href="#fn:4" rel="footnote">4</a></sup>.
This repository is a
+verbatim copy of the deployment repository on the master server and as such
needs to be
+replicated periodically. The configuration of the deployment provider consists
of three
+parts: a repository store, the repository servlet, and a repository
provider.</p>
+<p>To create a "slave" deployment repository<sup id="fnref:5"><a
class="footnote-ref" href="#fn:5" rel="footnote">5</a></sup> store, the
following configuration needs to
+be supplied to the <tt>org.apache.ace.server.repository.factory</tt> managed
service
+factory:</p>
+<div class="codehilite"><pre><span class="c"># the symbolic name of the
repository, should be "deployment"</span>
+<span class="na">name</span><span class="o">=</span><span
class="s">deployment</span>
+<span class="c"># the customer name, should be equal to the customer name used
on the master server</span>
+<span class="na">customer</span><span class="o">=</span><span
class="s">apache</span>
+<span class="c"># indicates that this is a slave/read-only repository</span>
+<span class="na">master</span><span class="o">=</span><span
class="s">false</span>
+</pre></div>
+
+
+<p>To make the repository store accessible through a servlet, we need to
supply the following
+configuration to the
<tt>org.apache.ace.repository.servlet.RepositoryServlet</tt> managed
+service:</p>
+<div class="codehilite"><pre><span class="c"># the endpoint on which the
deployment repository store is accessible</span>
+<span class="na">org.apache.ace.server.servlet.endpoint</span><span
class="o">=</span><span class="s">/repository</span>
+<span class="c"># whether or not to enable authentication for this
endpoint</span>
+<span class="na">authentication.enabled</span> <span class="o">=</span> <span
class="s">false</span>
+</pre></div>
+
+
+<p>This will instantiate a servlet that listens on the <tt>/repository</tt>
endpoint (for
+example, <tt>http://my.relay.server:8080/repository</tt>).</p>
+<p>With the repository store and servlet configured, we can configure the
deployment
+repository provider, which is used to collect information about deployment
artefacts that
+should be deployed on a target. The deployment repository provider is
configured by
+supplying the following configuration to the
+<tt>org.apache.ace.deployment.provider.repositorybased</tt> managed
service:</p>
+<div class="codehilite"><pre><span class="c"># the URL on which the deployment
repository store can be accessed</span>
+<span class="na">url</span> <span class="o">=</span> <span
class="s">http://my.relay.server:8080/repository</span>
+<span class="c"># the symbolic name of the repository, should be
"deployment"</span>
+<span class="na">name</span> <span class="o">=</span> <span
class="s">deployment</span>
+<span class="c"># the customer name, should be equal to the customer name used
on the master server</span>
+<span class="na">customer</span> <span class="o">=</span> <span
class="s">apache</span>
+</pre></div>
+
+
+<h2 id="deployment-servlet">Deployment servlet</h2>
+<p>The target is only interested in downloading deployment packages containing
the updates
+for its software and/or its management agent. To support this, two servlets
need to be
+instantiated, one for accessing the deployment packages of the target
software, and one
+for accessing the deployment packages for the management agent.</p>
+<p>To configure the servlet responsible for providing deployment packages of
the target
+software, we need to supply the following configuration to the
+<tt>org.apache.ace.deployment.servlet</tt> managed service:</p>
+<div class="codehilite"><pre><span class="c"># the endpoint on which the
deployment servlet for software-updates is accessible</span>
+<span class="na">org.apache.ace.server.servlet.endpoint</span><span
class="o">=</span><span class="s">/deployment</span>
+<span class="c"># whether or not to enable authentication for this
endpoint</span>
+<span class="na">authentication.enabled</span> <span class="o">=</span> <span
class="s">false</span>
+</pre></div>
+
+
+<p>To configure the servlet responsible for providing agent updates, we need
to supply the
+following configuration to the
<tt>org.apache.ace.deployment.servlet.agent</tt> managed
+service:</p>
+<div class="codehilite"><pre><span class="c"># the endpoint on which the
deployment servlet for agent-updates is accessible</span>
+<span class="na">org.apache.ace.server.servlet.endpoint</span><span
class="o">=</span><span class="s">/agent</span>
+<span class="c"># whether or not to enable authentication for this
endpoint</span>
+<span class="na">authentication.enabled</span> <span class="o">=</span> <span
class="s">false</span>
+<span class="c"># the OBR used for retrieving the agent software</span>
+<span class="na">obr.url</span> <span class="o">=</span> <span
class="s">http://my.obr.server:8080/obr/</span>
+</pre></div>
+
+
+<h2 id="task-scheduler">Task scheduler</h2>
+<p>With the synchronisation and repository replication tasks in place, we need
to tell the
+ACE scheduler to periodically execute these tasks. This is done by supplying
the following
+configuration to the <tt>org.apache.ace.scheduler.cfg</tt> managed service:</p>
+<div class="codehilite"><pre><span class="c"># execute all LogSyncTasks once
every 2 seconds...</span>
+<span class="na">org.apache.ace.log.server.task.LogSyncTask</span><span
class="o">=</span><span class="s">2000</span>
+<span class="c"># Synchronise with the master repository every 5 seconds...
</span>
+<span
class="na">org.apache.ace.repository.task.RepositoryReplicationTask</span><span
class="o">=</span><span class="s">5000</span>
+</pre></div>
+
+
+<p>The relay server is now completely configured and ready to serve its
targets. </p>
+<p>A complete runnable example can be found in the <tt>run-relay</tt> project
of the ACE
+source repository. This example project starts a relay server on
<tt>localhost:8282</tt>
+and expects its upstream server to run at <tt>localhost:8080</tt> A list of
all required
+bundles to run a relay server can be found in the <tt>relay.bndrun</tt>
file.</p>
+<h2 id="target-configuration">Target configuration</h2>
+<p>To only thing that a target needs to know about the relay server is its
(base) URL. This
+can be supplied when starting the management agent on the target by adding the
following
+argument to its command line:</p>
+<div class="codehilite"><pre>-Dagent.discovery.serverurls<span
class="o">=</span>http://my.relay.server:8080/
+</pre></div>
+
+
+<p>In fact, the <tt>agent.discovery.serverurls</tt> can take multiple server
URLs (separated
+by commas) to support a simple form of fail-over, like
+<tt>http://first.relay.server:8080/,http://second.relay.server:8080</tt>.</p>
+<h2 id="notes">Notes</h2>
+<div class="footnote">
+<hr />
+<ol>
+<li id="fn:1">
+<p>this symbolic name <em>must</em> be equal to the name used on the upstream
server. By
+default, the name <tt>auditlog</tt> is used; <a class="footnote-backref"
href="#fnref:1" rev="footnote" title="Jump back to footnote 1 in the
text">↩</a></p>
+</li>
+<li id="fn:2">
+<p>by convention, use the same name for the endpoint as is used for log
store; <a class="footnote-backref" href="#fnref:2" rev="footnote"
title="Jump back to footnote 2 in the text">↩</a></p>
+</li>
+<li id="fn:3">
+<p>the property-implementation of the ACE discovery service uses a simple
preconfigured
+property to "discover" the upstream server. The discovery service allows
other, more
+sophisticated, implementations to be used instead; <a
class="footnote-backref" href="#fnref:3" rev="footnote" title="Jump back to
footnote 3 in the text">↩</a></p>
+</li>
+<li id="fn:4">
+<p>the deployment repository contains all information about the different
deployment
+packages. Each deployment package is a set of artefacts that can be installed
on a target; <a class="footnote-backref" href="#fnref:4" rev="footnote"
title="Jump back to footnote 4 in the text">↩</a></p>
+</li>
+<li id="fn:5">
+<p>a slave repository is a repository that is not allowed to be changed and
receives
+its content from another (master) repository. <a class="footnote-backref"
href="#fnref:5" rev="footnote" title="Jump back to footnote 5 in the
text">↩</a></p>
+</li>
+</ol>
+</div></div>
+ <hr>
+ <footer>
+ <p>Copyright © 2012-2014 <a href="http://www.apache.org/";>The
Apache Software Foundation</a>, Licensed under the <a
href="http://www.apache.org/licenses/LICENSE-2.0";>Apache License, Version
2.0</a>.<br/>Apache ACE, the Apache ACE logo, Apache and the Apache feather
logo are trademarks of The Apache Software Foundation. All other marks
mentioned may be trademarks or registered trademarks of their respective
owners.</p>
+ </footer>
+ </div>
+ </body>
+</html>
Added:
websites/staging/ace/trunk/content/docs/deployment_strategy_classdiagram.svg
==============================================================================
Binary file - no diff available.
Propchange:
websites/staging/ace/trunk/content/docs/deployment_strategy_classdiagram.svg
------------------------------------------------------------------------------
svn:mime-type = image/svg+xml
Added:
websites/staging/ace/trunk/content/docs/deployment_strategy_update_seq.svg
==============================================================================
Binary file - no diff available.
Propchange:
websites/staging/ace/trunk/content/docs/deployment_strategy_update_seq.svg
------------------------------------------------------------------------------
svn:mime-type = image/svg+xml
Added: websites/staging/ace/trunk/content/docs/design/auditlog-protocol.html
==============================================================================
--- websites/staging/ace/trunk/content/docs/design/auditlog-protocol.html
(added)
+++ websites/staging/ace/trunk/content/docs/design/auditlog-protocol.html Mon
Nov 24 22:42:13 2014
@@ -0,0 +1,210 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+ <head>
+ <title>Audit Log Protocol</title>
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ <meta property="og:image" content="//www.apache.org/images/asf_logo.gif" />
+ <link href="/css/bootstrap.min.css" rel="stylesheet" media="screen">
+ <link href="/css/prettify.css" rel="stylesheet" media="screen">
+ <link href="/css/code.css" rel="stylesheet" media="screen">
+ <script src="//code.jquery.com/jquery.js"></script>
+ <script src="/js/bootstrap.min.js"></script>
+ <script src="/js/prettify.js"></script>
+
+
+
+ <script>
+ $(function () { prettyPrint() })
+ $().dropdown()
+ </script>
+ </head>
+ <body style="padding-top: 50px;">
+ <div class="navbar navbar-fixed-top navbar-inverse">
+ <div class="navbar-inner">
+ <div class="container">
+ <a class="brand" href="/index.html">Apache ACE™</a>
+ <ul class="nav">
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">News <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="/news.html">News</a>
+ </li>
+ <li>
+ <a href="/on-the-web.html">On the web</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="/downloads.html">Downloads</a>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Users <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="/user-doc/introduction.html">Introduction</a>
+ </li>
+ <li>
+ <a href="/user-doc/getting-started.html">Getting Started</a>
+ </li>
+ <li>
+ <a href="/user-doc/user-guide.html">User Guide</a>
+ </li>
+ <li>
+ <a href="/user-doc/features.html">Features</a>
+ </li>
+ <li>
+ <a href="/user-doc/shellapi.html">Client Shell API</a>
+ </li>
+ <li>
+ <a href="/user-doc/restapi.html">Client REST API</a>
+ </li>
+ <li>
+ <a href="/user-doc/useradmin-ui.html">User Management Guide</a>
+ </li>
+ <li>
+ <a href="/user-doc/faq.html">FAQ</a>
+ </li>
+ <li>
+ <a href="/user-doc/support.html">Support</a>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Developers <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="/dev-doc/getting-started.html">Getting Started</a>
+ </li>
+ <li>
+ <a href="/dev-doc/requirements/">Requirements</a>
+ </li>
+ <li>
+ <a href="/dev-doc/architecture.html">Architecture</a>
+ </li>
+ <li>
+ <a href="/dev-doc/analysis/">Analysis</a>
+ </li>
+ <li>
+ <a href="/dev-doc/design/">Design</a>
+ </li>
+ <li>
+ <a href="/dev-doc/coding-standards.html">Coding Standards</a>
+ </li>
+ <li>
+ <a href="/dev-doc/release-guide.html">Release Guide</a>
+ </li>
+ <li>
+ <a href="/dev-doc/writing-tests.html">Writing unit/integration
tests</a>
+ </li>
+ <li>
+ <a href="/dev-doc/adding-custom-artifact-types.html">Adding custom
artifact types</a>
+ </li>
+ <li>
+ <a href="/dev-doc/configuring-relay-servers.html">Configuring and
using relay servers</a>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Get Involved <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="/get-involved/mailing-lists.html">Mailing Lists</a>
+ </li>
+ <li>
+ <a href="/get-involved/issue-tracking.html">Issue Tracking</a>
+ </li>
+ <li>
+ <a href="/get-involved/continuous-integration.html">Continuous
Integration</a>
+ </li>
+ <li>
+ <a href="/get-involved/source-code.html">Source Code</a>
+ </li>
+ <li>
+ <a href="/get-involved/project-team.html">Project Team</a>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Wiki <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a
href="https://cwiki.apache.org/confluence/display/ACE/Board+Reports";>Board
Reports <i class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a
href="https://cwiki.apache.org/confluence/display/ACE/Index";>Homepage <i
class="icon-share-alt"></i></a>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Apache <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="http://www.apache.org/";>Apache Homepage <i
class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="http://www.apache.org/licenses/";>Licenses <i
class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="http://www.apache.org/security/";>Security <i
class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship <i
class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="http://www.apache.org/foundation/thanks.html";>Thanks <i
class="icon-share-alt"></i></a>
+ </li>
+ </ul>
+ </li>
+</ul>
+
+ </div>
+ </div>
+ </div>
+ <div class="container">
+ <p><a href="/"><i class='icon-home'></i> Home</a> » <a
href="/docs/">Docs</a> » <a href="/docs/design/">Design</a></p>
+ <h1>Audit Log Protocol</h1>
+ <div class="clear"></div>
+ <div id="content"><p>Audit logs record life cycle changes on targets. As
such, an audit log can be used to see changes over time and track what is
actually on a target. This design describes the protocol to exchange audit log
information.</p>
+<p>Each target has an audit log. If the log somehow gets lost on the target,
it will generate a new log with a new unique ID. A log contains entries, where
each entry gets a sequence number.</p>
+<h1 id="protocol">Protocol</h1>
+<p>The audit log protocol consists of three commands. The first command can be
used for two parties to exchange information about available audit log entry
sequence numbers. The other two commands allow you to send and receive data.</p>
+<h1 id="querying-log-information">Querying log information</h1>
+<p>This command can be used to exchange information about available audit log
entry sequence numbers. Information is exchanged between either a target and a
(relay) server, or a relay server and a server. You ask the other party what
sequence numbers it has, either for a specific target or for all targets. The
result is a collection of sequence numbers. You can then act on that, sending
the other party the entries it's missing and asking for entries you don't
have.</p>
+<ul>
+<li><code>GET auditlog/query</code> - returns a full list of sequence
numbers</li>
+<li><code>GET auditlog/query?gwid=myid&logid=2007-07-01</code> - returns
sequence numbers for a specific target</li>
+<li><code>GET auditlog/query?filter=(vendor='luminis')</code> - returns
sequence numbers for any target that matches the filter</li>
+</ul>
+<h3 id="about-queries">About queries</h3>
+<p>Queries (for log information or entries) come in three forms:</p>
+<ol>
+<li>Without any filter, you simply get everything.</li>
+<li>With a filter on certain keys, all values of specified keys will have to
match.</li>
+<li>With an LDAP filter, where you can filter on arbitrary keys and use
compound expressions and pattern matching.</li>
+</ol>
+<h1 id="sending-log-information">Sending log information</h1>
+<p>By sending log information, you're pushing it to the other party. You will
probably first have figured out, by querying, what data actually needs to be
sent.</p>
+<ul>
+<li>POST auditlog/send - returns status (ok, not ok)</li>
+</ul>
+<p>The data gets sent in the following format:</p>
+<div class="codehilite"><pre><span class="n">gwid</span><span
class="p">,</span> <span class="n">logid</span><span class="p">,</span> <span
class="n">seqnr</span><span class="p">,</span> <span
class="n">eventnumber</span><span class="p">,</span> <span
class="n">type</span> <span class="p">(,</span> <span class="n">key</span><span
class="p">,</span> <span class="n">value</span><span class="p">)</span><span
class="o">*</span>
+</pre></div>
+
+
+<p>Data is terminated by '\n' (a new-line).</p>
+<h1 id="receiving-log-information">Receiving log information</h1>
+<p>Here you're asking the other party for data. As part of the request, you
can ask for specific information about one or more targets. If you're not
specific, you will get everything.</p>
+<ul>
+<li><code>GET auditlog/receive</code> - returns list/collection of
elements</li>
+<li><code>GET auditlog/receive?gwid=myid</code> - (see querying)</li>
+<li><code>GET auditlog/receive?filter=(region='asia')</code> - ...</li>
+</ul></div>
+ <hr>
+ <footer>
+ <p>Copyright © 2012-2014 <a href="http://www.apache.org/";>The
Apache Software Foundation</a>, Licensed under the <a
href="http://www.apache.org/licenses/LICENSE-2.0";>Apache License, Version
2.0</a>.<br/>Apache ACE, the Apache ACE logo, Apache and the Apache feather
logo are trademarks of The Apache Software Foundation. All other marks
mentioned may be trademarks or registered trademarks of their respective
owners.</p>
+ </footer>
+ </div>
+ </body>
+</html>
Added: websites/staging/ace/trunk/content/docs/design/index.html
==============================================================================
--- websites/staging/ace/trunk/content/docs/design/index.html (added)
+++ websites/staging/ace/trunk/content/docs/design/index.html Mon Nov 24
22:42:13 2014
@@ -0,0 +1,186 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+ <head>
+ <title>Design</title>
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ <meta property="og:image" content="//www.apache.org/images/asf_logo.gif" />
+ <link href="/css/bootstrap.min.css" rel="stylesheet" media="screen">
+ <link href="/css/prettify.css" rel="stylesheet" media="screen">
+ <link href="/css/code.css" rel="stylesheet" media="screen">
+ <script src="//code.jquery.com/jquery.js"></script>
+ <script src="/js/bootstrap.min.js"></script>
+ <script src="/js/prettify.js"></script>
+
+
+
+ <script>
+ $(function () { prettyPrint() })
+ $().dropdown()
+ </script>
+ </head>
+ <body style="padding-top: 50px;">
+ <div class="navbar navbar-fixed-top navbar-inverse">
+ <div class="navbar-inner">
+ <div class="container">
+ <a class="brand" href="/index.html">Apache ACE™</a>
+ <ul class="nav">
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">News <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="/news.html">News</a>
+ </li>
+ <li>
+ <a href="/on-the-web.html">On the web</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="/downloads.html">Downloads</a>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Users <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="/user-doc/introduction.html">Introduction</a>
+ </li>
+ <li>
+ <a href="/user-doc/getting-started.html">Getting Started</a>
+ </li>
+ <li>
+ <a href="/user-doc/user-guide.html">User Guide</a>
+ </li>
+ <li>
+ <a href="/user-doc/features.html">Features</a>
+ </li>
+ <li>
+ <a href="/user-doc/shellapi.html">Client Shell API</a>
+ </li>
+ <li>
+ <a href="/user-doc/restapi.html">Client REST API</a>
+ </li>
+ <li>
+ <a href="/user-doc/useradmin-ui.html">User Management Guide</a>
+ </li>
+ <li>
+ <a href="/user-doc/faq.html">FAQ</a>
+ </li>
+ <li>
+ <a href="/user-doc/support.html">Support</a>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Developers <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="/dev-doc/getting-started.html">Getting Started</a>
+ </li>
+ <li>
+ <a href="/dev-doc/requirements/">Requirements</a>
+ </li>
+ <li>
+ <a href="/dev-doc/architecture.html">Architecture</a>
+ </li>
+ <li>
+ <a href="/dev-doc/analysis/">Analysis</a>
+ </li>
+ <li>
+ <a href="/dev-doc/design/">Design</a>
+ </li>
+ <li>
+ <a href="/dev-doc/coding-standards.html">Coding Standards</a>
+ </li>
+ <li>
+ <a href="/dev-doc/release-guide.html">Release Guide</a>
+ </li>
+ <li>
+ <a href="/dev-doc/writing-tests.html">Writing unit/integration
tests</a>
+ </li>
+ <li>
+ <a href="/dev-doc/adding-custom-artifact-types.html">Adding custom
artifact types</a>
+ </li>
+ <li>
+ <a href="/dev-doc/configuring-relay-servers.html">Configuring and
using relay servers</a>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Get Involved <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="/get-involved/mailing-lists.html">Mailing Lists</a>
+ </li>
+ <li>
+ <a href="/get-involved/issue-tracking.html">Issue Tracking</a>
+ </li>
+ <li>
+ <a href="/get-involved/continuous-integration.html">Continuous
Integration</a>
+ </li>
+ <li>
+ <a href="/get-involved/source-code.html">Source Code</a>
+ </li>
+ <li>
+ <a href="/get-involved/project-team.html">Project Team</a>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Wiki <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a
href="https://cwiki.apache.org/confluence/display/ACE/Board+Reports";>Board
Reports <i class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a
href="https://cwiki.apache.org/confluence/display/ACE/Index";>Homepage <i
class="icon-share-alt"></i></a>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Apache <b
class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="http://www.apache.org/";>Apache Homepage <i
class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="http://www.apache.org/licenses/";>Licenses <i
class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="http://www.apache.org/security/";>Security <i
class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship <i
class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="http://www.apache.org/foundation/thanks.html";>Thanks <i
class="icon-share-alt"></i></a>
+ </li>
+ </ul>
+ </li>
+</ul>
+
+ </div>
+ </div>
+ </div>
+ <div class="container">
+ <p><a href="/"><i class='icon-home'></i> Home</a> » <a
href="/docs/">Docs</a> » <a href="/docs/design/">Design</a></p>
+ <h1>Design</h1>
+ <div class="clear"></div>
+ <div id="content"><h2 id="articleshow-tos">Articles/how to's</h2>
+<ul>
+<li><a href="ace-deployment-strategies.html">Customizing Deployment
Strategies</a></li>
+<li><a href="ace-authentication.html">Configuring ACE authentication</a></li>
+<li><a href="using-client-certificates.html">Using client certificates
authentication</a></li>
+</ul>
+<h2 id="miscellaneous">Miscellaneous</h2>
+<ul>
+<li><a href="remote-interfaces.html">Remote Interfaces</a></li>
+<li><a href="test-script.html">Test Script</a></li>
+<li><a href="auditlog-protocol.html">Audit Log Protocol</a></li>
+</ul></div>
+ <hr>
+ <footer>
+ <p>Copyright © 2012-2014 <a href="http://www.apache.org/";>The
Apache Software Foundation</a>, Licensed under the <a
href="http://www.apache.org/licenses/LICENSE-2.0";>Apache License, Version
2.0</a>.<br/>Apache ACE, the Apache ACE logo, Apache and the Apache feather
logo are trademarks of The Apache Software Foundation. All other marks
mentioned may be trademarks or registered trademarks of their respective
owners.</p>
+ </footer>
+ </div>
+ </body>
+</html>
Added:
websites/staging/ace/trunk/content/docs/design/remote-interfaces-components.svg
==============================================================================
Binary file - no diff available.
Propchange:
websites/staging/ace/trunk/content/docs/design/remote-interfaces-components.svg
------------------------------------------------------------------------------
svn:mime-type = image/svg+xml
