You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@slider.apache.org by bi...@apache.org on 2014/05/30 18:47:16 UTC
svn commit: r1598665 [15/16] - in /incubator/slider/site/content: ./
architecture/ configuration/ css/ developing/ images/ images/logos/
images/profiles/ img/ js/ registry/ release_notes/ slider_specs/
specification/
Added: incubator/slider/site/content/specification/cli-actions.html
URL: http://svn.apache.org/viewvc/incubator/slider/site/content/specification/cli-actions.html?rev=1598665&view=auto
==============================================================================
--- incubator/slider/site/content/specification/cli-actions.html (added)
+++ incubator/slider/site/content/specification/cli-actions.html Fri May 30 16:47:13 2014
@@ -0,0 +1,790 @@
+<!DOCTYPE html>
+<!--
+ | Generated by Apache Maven Doxia at 2014-05-30
+ | Rendered using Apache Maven Fluido Skin 1.3.0
+-->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <meta name="Date-Revision-yyyymmdd" content="20140530" />
+ <meta http-equiv="Content-Language" content="en" />
+ <title>Apache Slider 0.30 (incubating) - </title>
+ <link rel="stylesheet" href="../css/apache-maven-fluido-1.3.0.min.css" />
+ <link rel="stylesheet" href="../css/site.css" />
+ <link rel="stylesheet" href="../css/print.css" media="print" />
+
+
+ <script type="text/javascript" src="../js/apache-maven-fluido-1.3.0.min.js"></script>
+
+
+ </head>
+ <body class="topBarEnabled">
+
+
+
+
+
+ <div id="topbar" class="navbar navbar-fixed-top ">
+ <div class="navbar-inner">
+ <div class="container"><div class="nav-collapse">
+
+
+ <ul class="nav">
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Project Documentation <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li class="dropdown-submenu">
+ <a href="../project-info.html" title="Project Information">Project Information</a>
+ <ul class="dropdown-menu">
+ <li> <a href="../index.html" title="About">About</a>
+</li>
+ <li> <a href="../plugin-management.html" title="Plugin Management">Plugin Management</a>
+</li>
+ <li> <a href="../distribution-management.html" title="Distribution Management">Distribution Management</a>
+</li>
+ <li> <a href="../dependency-info.html" title="Dependency Information">Dependency Information</a>
+</li>
+ <li> <a href="../dependency-convergence.html" title="Dependency Convergence">Dependency Convergence</a>
+</li>
+ <li> <a href="../source-repository.html" title="Source Repository">Source Repository</a>
+</li>
+ <li> <a href="../mail-lists.html" title="Mailing Lists">Mailing Lists</a>
+</li>
+ <li> <a href="../issue-tracking.html" title="Issue Tracking">Issue Tracking</a>
+</li>
+ <li> <a href="../integration.html" title="Continuous Integration">Continuous Integration</a>
+</li>
+ <li> <a href="../plugins.html" title="Project Plugins">Project Plugins</a>
+</li>
+ <li> <a href="../license.html" title="Project License">Project License</a>
+</li>
+ <li> <a href="../modules.html" title="Project Modules">Project Modules</a>
+</li>
+ <li> <a href="../dependency-management.html" title="Dependency Management">Dependency Management</a>
+</li>
+ <li> <a href="../team-list.html" title="Project Team">Project Team</a>
+</li>
+ <li> <a href="../project-summary.html" title="Project Summary">Project Summary</a>
+</li>
+ <li> <a href="../dependencies.html" title="Dependencies">Dependencies</a>
+</li>
+ </ul>
+ </li>
+
+ <li class="dropdown-submenu">
+ <a href="../project-reports.html" title="Project Reports">Project Reports</a>
+ <ul class="dropdown-menu">
+ <li> <a href="../surefire-report.html" title="Surefire Report">Surefire Report</a>
+</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documents <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="../getting_started.html" title="Getting Started">Getting Started</a>
+</li>
+
+ <li> <a href="../manpage.html" title="manpage">manpage</a>
+</li>
+
+ <li> <a href="../troubleshooting.html" title="Troubleshooting">Troubleshooting</a>
+</li>
+
+ <li> <a href="../architecture/index.html" title="Architecture">Architecture</a>
+</li>
+
+ <li> <a href="../developing/index.html" title="Developing">Developing</a>
+</li>
+
+ <li> <a href="../exitcodes.html" title="Exitcodes">Exitcodes</a>
+</li>
+ </ul>
+ </li>
+ </ul>
+
+
+
+
+ </div>
+
+ </div>
+ </div>
+ </div>
+
+ <div class="container">
+ <div id="banner">
+ <div class="pull-left">
+ <a href=".././" id="bannerLeft">
+ <h2>Apache Slider (incubating)</h2>
+ </a>
+ </div>
+ <div class="pull-right"> <div id="bannerRight">
+ <img src="http://incubator.apache.org/images/apache-incubator-logo.png" />
+ </div>
+ </div>
+ <div class="clear"><hr/></div>
+ </div>
+
+ <div id="breadcrumbs">
+ <ul class="breadcrumb">
+
+
+ <li id="publishDate">Last Published: 2014-05-30</li>
+
+
+
+ <li id="projectVersion" class="pull-right">Version: 0.30</li>
+
+ </ul>
+ </div>
+
+
+
+ <div id="bodyColumn" >
+
+ <!-- -
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License. --><h1>Apache Slider CLI Actions</h1>
+<div class="section">
+<h2>Important<a name="Important"></a></h2>
+
+<ol style="list-style-type: decimal">
+
+<li>This document is still being updated from the original hoya design</li>
+
+<li>The new cluster model of separated specification files for internal, resource and application configuration has not been incorporated.</li>
+
+<li>What is up to date is the CLI command list and arguments</li>
+</ol></div>
+<div class="section">
+<h2>client configuration<a name="client_configuration"></a></h2>
+<p>As well as the CLI options, the <tt>conf/slider-client.xml</tt> XML file can define arguments used to communicate with the Application instance</p>
+<div class="section">
+<div class="section">
+<h4><tt>fs.defaultFS</tt><a name="fs.defaultFS"></a></h4>
+<p>Equivalent to setting the filesystem with <tt>--filesystem</tt></p></div></div></div>
+<div class="section">
+<h2>Common<a name="Common"></a></h2>
+<div class="section">
+<h3>System Properties<a name="System_Properties"></a></h3>
+<p>Arguments of the form <tt>-S key=value</tt> define JVM system properties.</p>
+<p>These are supported primarily to define options needed for some Kerberos configurations.</p></div>
+<div class="section">
+<h3>Definitions<a name="Definitions"></a></h3>
+<p>Arguments of the form <tt>-D key=value</tt> define JVM system properties.</p>
+<p>These can define client options that are not set in <tt>conf/slider-client.xml</tt> - or to override them.</p></div>
+<div class="section">
+<h3>Cluster names<a name="Cluster_names"></a></h3>
+<p>All actions that must take an instance name will fail with <tt>EXIT_UNKNOWN_INSTANCE</tt> if one is not provided.</p></div></div>
+<div class="section">
+<h2>Action: Build<a name="Action:_Build"></a></h2>
+<p>Builds a cluster -creates all the on-filesystem datastructures, and generates a cluster description that is both well-defined and deployable -<i>but does not actually start the cluster</i></p>
+
+<div class="source">
+<pre>build (instancename,
+ options:List[(String,String)],
+ components:List[(String, int)],
+ componentOptions:List[(String,String, String)],
+ resourceOptions:List[(String,String)],
+ resourceComponentOptions:List[(String,String, String)],
+ confdir: URI,
+ provider: String
+ zkhosts,
+ zkport,
+ image
+ apphome
+ appconfdir
+</pre></div>
+<div class="section">
+<div class="section">
+<h4>Preconditions<a name="Preconditions"></a></h4>
+<p>(Note that the ordering of these preconditions is not guaranteed to remain constant)</p>
+<p>The instance name is valid</p>
+
+<div class="source">
+<pre>if not valid-instance-name(instancename) : raise SliderException(EXIT_COMMAND_ARGUMENT_ERROR)
+</pre></div>
+<p>The instance must not be live. This is purely a safety check as the next test should have the same effect.</p>
+
+<div class="source">
+<pre>if slider-instance-live(YARN, instancename) : raise SliderException(EXIT_CLUSTER_IN_USE)
+</pre></div>
+<p>The instance must not exist</p>
+
+<div class="source">
+<pre>if is-dir(HDFS, instance-path(FS, instancename)) : raise SliderException(EXIT_CLUSTER_EXISTS)
+</pre></div>
+<p>The configuration directory must exist it does not have to be the instance’s HDFS instance, as it will be copied there -and must contain only files</p>
+
+<div class="source">
+<pre>let FS = FileSystem.get(appconfdir)
+if not isDir(FS, appconfdir) raise SliderException(EXIT_COMMAND_ARGUMENT_ERROR)
+forall f in children(FS, appconfdir) :
+ if not isFile(f): raise IOException
+</pre></div>
+<p>There’s a race condition at build time where between the preconditions being met and the instance specification being saved, the instance is created by another process. This addressed by creating a lock file, <tt>writelock.json</tt> in the destination directory. If the file exists, no other process may acquire the lock.</p>
+<p>There is a less exclusive readlock file, <tt>readlock.json</tt> which may be created by any process that wishes to read the configuration. If it exists when another process wishes to access the files, the subsequent process may read the data, but MUST NOT delete it afterwards. A process attempting to acquire the writelock must check for the existence of this file before AND after creating the writelock file, failing if its present. This retains a small race condition: a second or later reader may still be reading the data when a process successfully acquires the write lock. If this proves to be an issue, a stricter model could be implemented, with each reading process creating a unique named readlock- file.</p></div>
+<div class="section">
+<h4>Postconditions<a name="Postconditions"></a></h4>
+<p>All the instance directories exist</p>
+
+<div class="source">
+<pre>is-dir(HDFS', instance-path(HDFS', instancename))
+is-dir(HDFS', original-conf-path(HDFS', instancename))
+is-dir(HDFS', generated-conf-path(HDFS', instancename))
+</pre></div>
+<p>The application cluster specification saved is well-defined and deployable</p>
+
+<div class="source">
+<pre>let instance-description = parse(data(HDFS', instance-json-path(HDFS', instancename)))
+well-defined-instance(instance-description)
+deployable-application-instance(HDFS', instance-description)
+</pre></div>
+<p>More precisely: the specification generated before it is saved as JSON is well-defined and deployable; no JSON file will be created if the validation fails.</p>
+<p>Fields in the cluster description have been filled in</p>
+
+<div class="source">
+<pre>internal.global["internal.provider.name"] == provider
+app_conf.global["zookeeper.port"] == zkport
+app_conf.global["zookeeper.hosts"] == zkhosts
+
+
+package => app_conf.global["agent.package"] = package
+</pre></div>
+<p>Any <tt>apphome</tt> and <tt>image</tt> properties have propagated</p>
+
+<div class="source">
+<pre>apphome == null or clusterspec.options["cluster.application.home"] == apphome
+image == null or clusterspec.options["cluster.application.image.path"] == image
+</pre></div>
+<p>(The <tt>well-defined-application-instance()</tt> requirement above defines the valid states of this pair of options)</p>
+<p>All role sizes have been mapped to <tt>component.instances</tt> fields</p>
+
+<div class="source">
+<pre>forall (name, size) in components :
+ resources.components[name]["components.instances"] == size
+</pre></div>
+<p>All option parameters have been added to the <tt>options</tt> map in the specification</p>
+
+<div class="source">
+<pre>forall (opt, val) in options :
+ app_conf.global[opt] == val
+
+forall (opt, val) in resourceOptions :
+ resource.global[opt] == val
+</pre></div>
+<p>All component option parameters have been added to the specific components’s option map in the relevant configuration file</p>
+
+<div class="source">
+<pre>forall (name, opt, val) in componentOptions :
+ app_conf.components[name][opt] == val
+
+forall (name, opt, val) in resourceComponentOptions :
+ resourceComponentOptions.components[name][opt] == val
+</pre></div>
+<p>To avoid some confusion as to where keys go, all options beginning with the prefix <tt>component.</tt> are automatically copied into the resources file:</p>
+
+<div class="source">
+<pre>forall (opt, val) in options where startswith(opt, "component.")
+ or startswith(opt, "role.")
+ or startswith(opt, "yarn."):
+ resource.global[opt] == val
+
+forall (name, opt, val) in componentOptions where startswith(opt, "component.")
+ or startswith(opt, "role.")
+ or startswith(opt, "yarn."):
+ resourceComponentOptions.components[name][opt] == val
+</pre></div>
+<p>There’s no explicit rejection of duplicate options, the outcome of that state is ‘undefined’. </p>
+<p>What is defined is that if Slider or its provider provided a default option value, the command-line supplied option will override it.</p>
+<p>All files that were in the configuration directory are now copied into the “original” configuration directory</p>
+
+<div class="source">
+<pre>let FS = FileSystem.get(appconfdir)
+let dest = original-conf-path(HDFS', instancename)
+forall [c in children(FS, confdir) :
+ data(HDFS', dest + [filename(c)]) == data(FS, c)
+</pre></div>
+<p>All files that were in the configuration directory now have equivalents in the generated configuration directory</p>
+
+<div class="source">
+<pre>let FS = FileSystem.get(appconfdir)
+let dest = generated-conf-path(HDFS', instancename)
+forall [c in children(FS, confdir) :
+ isfile(HDFS', dest + [filename(c)])
+</pre></div></div></div></div>
+<div class="section">
+<h2>Action: Thaw<a name="Action:_Thaw"></a></h2>
+
+<div class="source">
+<pre>thaw <instancename> [--wait <timeout>]
+</pre></div>
+<p>Thaw takes an application instance with configuration and (possibly) data on disk, and attempts to create a live application with the specified number of nodes</p>
+<div class="section">
+<div class="section">
+<h4>Preconditions<a name="Preconditions"></a></h4>
+
+<div class="source">
+<pre>if not valid-instance-name(instancename) : raise SliderException(EXIT_COMMAND_ARGUMENT_ERROR)
+</pre></div>
+<p>The cluster must not be live. This is purely a safety check as the next test should have the same effect.</p>
+
+<div class="source">
+<pre>if slider-instance-live(YARN, instancename) : raise SliderException(EXIT_CLUSTER_IN_USE)
+</pre></div>
+<p>The cluster must not exist</p>
+
+<div class="source">
+<pre>if is-dir(HDFS, application-instance-path(FS, instancename)) : raise SliderException(EXIT_CLUSTER_EXISTS)
+</pre></div>
+<p>The cluster specification must exist, be valid and deployable</p>
+
+<div class="source">
+<pre>if not is-file(HDFS, cluster-json-path(HDFS, instancename)) : SliderException(EXIT_UNKNOWN_INSTANCE)
+if not well-defined-application-instance(HDFS, application-instance-path(HDFS, instancename)) : raise SliderException(EXIT_BAD_CLUSTER_STATE)
+if not deployable-application-instance(HDFS, application-instance-path(HDFS, instancename)) : raise SliderException(EXIT_BAD_CLUSTER_STATE)
+</pre></div></div></div>
+<div class="section">
+<h3>Postconditions<a name="Postconditions"></a></h3>
+<p>After the thaw has been performed, there is now a queued request in YARN for the chosen (how?) queue</p>
+
+<div class="source">
+<pre>YARN'.Queues'[amqueue] = YARN.Queues[amqueue] + [launch("slider", instancename, requirements, context)]
+</pre></div>
+<p>If a wait timeout was specified, the cli waits until the application is considered running by YARN (the AM is running), the wait timeout has been reached, or the application has failed</p>
+
+<div class="source">
+<pre>waittime < 0 or (exists a in slider-running-application-instances(yarn-application-instances(YARN', instancename, user))
+ where a.YarnApplicationState == RUNNING)
+</pre></div></div></div>
+<div class="section">
+<h2>Outcome: AM-launched state<a name="Outcome:_AM-launched_state"></a></h2>
+<p>Some time after the AM was queued, if the relevant prerequisites of the launch request are met, the AM will be deployed</p>
+<div class="section">
+<div class="section">
+<h4>Preconditions<a name="Preconditions"></a></h4>
+
+<ul>
+
+<li>The resources referenced in HDFS (still) are accessible by the user</li>
+
+<li>The requested YARN memory and core requirements could be met on the YARN cluster and specific YARN application queue.</li>
+
+<li>There is sufficient capacity in the YARN cluster to create a container for the AM.</li>
+</ul></div>
+<div class="section">
+<h4>Postconditions<a name="Postconditions"></a></h4>
+<p>Define a YARN state at a specific time <tt>t</tt> as <tt>YARN(t)</tt>; the fact that an AM is launched afterwards</p>
+<p>The AM is deployed if there is some time <tt>t</tt> after the submission time <tt>t0</tt> where the application is listed </p>
+
+<div class="source">
+<pre>exists t1 where t1 > t0 and slider-instance-live(YARN(t1), user, instancename)
+</pre></div>
+<p>At which time there is a container in the cluster hosting the AM -it’s context is the launch context</p>
+
+<div class="source">
+<pre>exists c in containers(YARN(t1)) where container.context = launch.context
+</pre></div>
+<p>There’s no way to determine when this time <tt>t1</tt> will be reached -or if it ever will -its launch may be postponed due to a lack of resources and/or higher priority requests using resources as they become available.</p>
+<p>For tests on a dedicated YARN cluster, a few tens of seconds appear to be enough for the AM-launched state to be reached, a failure to occur, or to conclude that the resource requirements are unsatisfiable.</p></div></div></div>
+<div class="section">
+<h2>Outcome: AM-started state<a name="Outcome:_AM-started_state"></a></h2>
+<p>A (usually short) time after the AM is launched, it should start</p>
+
+<ul>
+
+<li>The node hosting the container is working reliably</li>
+
+<li>The supplied command line could start the process</li>
+
+<li>the localized resources in the context could be copied to the container (which implies that they are readable by the user account the AM is running under)</li>
+
+<li>The combined classpath of YARN, extra JAR files included in the launch context, and the resources in the slider client ‘conf’ dir contain all necessary dependencies to run Slider.</li>
+
+<li>There’s no issue with the cluster specification that causes the AM to exit with an error code.</li>
+</ul>
+<p>Node failures/command line failures are treated by YARN as an AM failure which will trigger a restart attempt -this may be on the same or a different node.</p>
+<div class="section">
+<div class="section">
+<h4>preconditions<a name="preconditions"></a></h4>
+<p>The AM was launched at an earlier time, <tt>t1</tt></p>
+
+<div class="source">
+<pre>exists t1 where t1 > t0 and am-launched(YARN(t1)
+</pre></div></div>
+<div class="section">
+<h4>Postconditions<a name="Postconditions"></a></h4>
+<p>The application is actually started if it is listed in the YARN application list as being in the state <tt>RUNNING</tt>, an RPC port has been registered with YARN (visible as the <tt>rpcPort</tt> attribute in the YARN Application Report,and that port is servicing RPC requests from authenticated callers.</p>
+
+<div class="source">
+<pre>exists t2 where:
+ t2 > t1
+ and slider-instance-live(YARN(t2), YARN, instancename, user)
+ and slider-live-instances(YARN(t2))[0].rpcPort != 0
+ and rpc-connection(slider-live-instances(YARN(t2))[0], SliderClusterProtocol)
+</pre></div>
+<p>A test for accepting cluster requests is querying the cluster status with <tt>SliderClusterProtocol.getJSONClusterStatus()</tt>. If this returns a parseable cluster description, the AM considers itself live.</p></div></div></div>
+<div class="section">
+<h2>Outcome: Applicaton Instance operational state<a name="Outcome:_Applicaton_Instance_operational_state"></a></h2>
+<p>Once started, Slider enters the operational state of trying to keep the numbers of live role instances matching the numbers specified in the cluster specification.</p>
+<p>The AM must request the a container for each desired instance of a specific roles of the application, wait for those requests to be granted, and then instantiate the specific application roles on the allocated containers.</p>
+<p>Such a request is made on startup, whenever a failure occurs, or when the cluster size is dynamically updated.</p>
+<p>The AM releases containers when the cluster size is shrunk during a flex operation, or during teardown.</p>
+<div class="section">
+<h3>steady state condition<a name="steady_state_condition"></a></h3>
+<p>The steady state of a Slider cluster is that the number of live instances of a role, plus the number of requested instances , minus the number of instances for which release requests have been made must match that of the desired number.</p>
+<p>If the internal state of the Slider AM is defined as <tt>AppState</tt></p>
+
+<div class="source">
+<pre>forall r in clusterspec.roles :
+ r["yarn.component.instances"] ==
+ AppState.Roles[r].live + AppState.Roles[r].requested - AppState.Roles[r].released
+</pre></div>
+<p>The <tt>AppState</tt> represents Slider’s view of the external YARN system state, based on its history of notifications received from YARN. </p>
+<p>It is indirectly observable from the cluster state which an AM can be queried for</p>
+
+<div class="source">
+<pre>forall r in AM.getJSONClusterStatus().roles :
+ r["yarn.component.instances"] ==
+ r["role.actual.instances"] + r["role.requested.instances"] - r["role.releasing.instances"]
+</pre></div>
+<p>Slider does not consider it an error if the number of actual instances remains below the desired value (i.e. outstanding requests are not being satisfied) -this is an operational state of the cluster that Slider cannot address.</p></div>
+<div class="section">
+<h3>Cluster startup<a name="Cluster_startup"></a></h3>
+<p>On a healthy dedicated test cluster, the time for the requests to be satisfied is a few tens of seconds at most: a failure to achieve this state is a sign of a problem.</p></div>
+<div class="section">
+<h3>Node or process failure<a name="Node_or_process_failure"></a></h3>
+<p>After a container or node failure, a new container for a new instance of that role is requested.</p>
+<p>The failure count is incremented -it can be accessed via the <tt>"role.failed.instances"</tt> attribute of a role in the status report.</p>
+<p>The number of failures of a role is tracked, and used by Slider as to when to conclude that the role is somehow failing consistently -and it should fail the entire application.</p>
+<p>This has initially been implemented as a simple counter, with the cluster option: <tt>"slider.container.failure.threshold"</tt> defining that threshold.</p>
+
+<div class="source">
+<pre>let status = AM.getJSONClusterStatus()
+forall r in in status.roles :
+ r["role.failed.instances"] < status.options["slider.container.failure.threshold"]
+</pre></div></div>
+<div class="section">
+<h3>Instance startup failure<a name="Instance_startup_failure"></a></h3>
+<p>Startup failures are measured alongside general node failures.</p>
+<p>A container is deemed to have failed to start if either of the following conditions were met:</p>
+
+<ol style="list-style-type: decimal">
+
+<li>
+<p>The AM received an <tt>onNodeManagerContainerStartFailed</tt> event.</p></li>
+
+<li>
+<p>The AM received an <tt>onCompletedNode</tt> event on a node that started less than a specified number of seconds earlier -a number given in the cluster option <tt>"slider.container.failure.shortlife"</tt>. </p></li>
+</ol>
+<p>More sophisticated failure handling logic than is currently implemented may treat startup failures differently from ongoing failures -as they can usually be treated as a sign that the container is failing to launch the program reliably - either the generated command line is invalid, or the application is failing to run/exiting on or nearly immediately.</p></div></div>
+<div class="section">
+<h2>Action: Create<a name="Action:_Create"></a></h2>
+<p>Create is simply <tt>build</tt> + <tt>thaw</tt> in sequence - the postconditions from the first action are intended to match the preconditions of the second.</p></div>
+<div class="section">
+<h2>Action: Freeze<a name="Action:_Freeze"></a></h2>
+
+<div class="source">
+<pre>freeze instancename [--wait time] [--message message]
+</pre></div>
+<p>The <i>freeze</i> action “freezes” the cluster: all its nodes running in the YARN cluster are stopped, leaving all the persistent state.</p>
+<p>The operation is intended to be idempotent: it is not an error if freeze is invoked on an already frozen cluster</p>
+<div class="section">
+<div class="section">
+<h4>Preconditions<a name="Preconditions"></a></h4>
+<p>The cluster name is valid and it matches a known cluster </p>
+
+<div class="source">
+<pre>if not valid-instance-name(instancename) : raise SliderException(EXIT_COMMAND_ARGUMENT_ERROR)
+
+if not is-file(HDFS, application-instance-path(HDFS, instancename)) :
+ raise SliderException(EXIT_UNKNOWN_INSTANCE)
+</pre></div></div>
+<div class="section">
+<h4>Postconditions<a name="Postconditions"></a></h4>
+<p>If the cluster was running, an RPC call has been sent to it <tt>stopCluster(message)</tt></p>
+<p>If the <tt>--wait</tt> argument specified a wait time, then the command will block until the cluster has finished or the wait time was exceeded. </p>
+<p>If the <tt>--message</tt> argument specified a message -it must appear in the YARN logs as the reason the cluster was frozen.</p>
+<p>The outcome should be the same:</p>
+
+<div class="source">
+<pre>not slider-instance-live(YARN', instancename)
+</pre></div></div></div></div>
+<div class="section">
+<h2>Action: Flex<a name="Action:_Flex"></a></h2>
+<p>Flex the cluster size: add or remove roles. </p>
+
+<div class="source">
+<pre>flex instancename
+components:List[(String, int)]
+</pre></div>
+
+<ol style="list-style-type: decimal">
+
+<li>The JSON cluster specification in the filesystem is updated</li>
+
+<li>if the cluster is running, it is given the new cluster specification, which will change the desired steady-state of the application</li>
+</ol>
+<div class="section">
+<div class="section">
+<h4>Preconditions<a name="Preconditions"></a></h4>
+
+<div class="source">
+<pre>if not is-file(HDFS, cluster-json-path(HDFS, instancename)) :
+ raise SliderException(EXIT_UNKNOWN_INSTANCE)
+</pre></div></div>
+<div class="section">
+<h4>Postconditions<a name="Postconditions"></a></h4>
+
+<div class="source">
+<pre>let originalSpec = data(HDFS, cluster-json-path(HDFS, instancename))
+
+let updatedSpec = originalspec where:
+ forall (name, size) in components :
+ updatedSpec.roles[name]["yarn.component.instances"] == size
+data(HDFS', cluster-json-path(HDFS', instancename)) == updatedSpec
+rpc-connection(slider-live-instances(YARN(t2))[0], SliderClusterProtocol)
+let flexed = rpc-connection(slider-live-instances(YARN(t2))[0], SliderClusterProtocol).flexClusterupdatedSpec)
+</pre></div></div>
+<div class="section">
+<h4>AM actions on flex<a name="AM_actions_on_flex"></a></h4>
+
+<div class="source">
+<pre>boolean SliderAppMaster.flexCluster(ClusterDescription updatedSpec)
+</pre></div>
+<p>If the cluster is in a state where flexing is possible (i.e. it is not in teardown), then <tt>AppState</tt> is updated with the new desired role counts. The operation will return once all requests to add or remove role instances have been queued, and be <tt>True</tt> iff the desired steady state of the cluster has been changed.</p></div>
+<div class="section">
+<h4>Preconditions<a name="Preconditions"></a></h4>
+
+<div class="source">
+<pre> well-defined-application-instance(HDFS, updatedSpec)
+</pre></div></div>
+<div class="section">
+<h4>Postconditions<a name="Postconditions"></a></h4>
+
+<div class="source">
+<pre>forall role in AppState.Roles.keys:
+ AppState'.Roles'[role].desiredCount = updatedSpec[roles]["yarn.component.instances"]
+result = AppState' != AppState
+</pre></div>
+<p>The flexing may change the desired steady state of the cluster, in which case the relevant requests will have been queued by the completion of the action. It is not possible to state whether or when the requests will be satisfied.</p></div></div></div>
+<div class="section">
+<h2>Action: Destroy<a name="Action:_Destroy"></a></h2>
+<p>Idempotent operation to destroy a frozen cluster -it succeeds if the cluster has already been destroyed/is unknown, but not if it is actually running.</p>
+<div class="section">
+<div class="section">
+<h4>Preconditions<a name="Preconditions"></a></h4>
+
+<div class="source">
+<pre>if not valid-instance-name(instancename) : raise SliderException(EXIT_COMMAND_ARGUMENT_ERROR)
+
+if slider-instance-live(YARN, instancename) : raise SliderException(EXIT_CLUSTER_IN_USE)
+</pre></div></div>
+<div class="section">
+<h4>Postconditions<a name="Postconditions"></a></h4>
+<p>The cluster directory and all its children do not exist</p>
+
+<div class="source">
+<pre>not is-dir(HDFS', application-instance-path(HDFS', instancename))
+</pre></div></div></div></div>
+<div class="section">
+<h2>Action: Status<a name="Action:_Status"></a></h2>
+
+<div class="source">
+<pre>status instancename [--out outfile]
+2
+</pre></div>
+<div class="section">
+<div class="section">
+<h4>Preconditions<a name="Preconditions"></a></h4>
+
+<div class="source">
+<pre>if not slider-instance-live(YARN, instancename) : raise SliderException(EXIT_UNKNOWN_INSTANCE)
+</pre></div></div>
+<div class="section">
+<h4>Postconditions<a name="Postconditions"></a></h4>
+<p>The status of the application has been successfully queried and printed out:</p>
+
+<div class="source">
+<pre>let status = slider-live-instances(YARN).rpcPort.getJSONClusterStatus()
+</pre></div>
+<p>if the <tt>outfile</tt> value is not defined then the status appears part of stdout</p>
+
+<div class="source">
+<pre>status in STDOUT'
+</pre></div>
+<p>otherwise, the outfile exists in the local filesystem</p>
+
+<div class="source">
+<pre>(outfile != "") ==> data(LocalFS', outfile) == body
+(outfile != "") ==> body in STDOUT'
+</pre></div></div></div></div>
+<div class="section">
+<h2>Action: Exists<a name="Action:_Exists"></a></h2>
+<p>This probes for a named cluster being defined or actually being in the running state.</p>
+<p>In the running state; it is essentially the status operation with only the exit code returned</p>
+<div class="section">
+<div class="section">
+<h4>Preconditions<a name="Preconditions"></a></h4>
+
+<div class="source">
+<pre>if not is-file(HDFS, application-instance-path(HDFS, instancename)) :
+ raise SliderException(EXIT_UNKNOWN_INSTANCE)
+</pre></div></div>
+<div class="section">
+<h4>Postconditions<a name="Postconditions"></a></h4>
+<p>The operation succeeds if the cluster is running and the RPC call returns the cluster status.</p>
+
+<div class="source">
+<pre>if live and not slider-instance-live(YARN, instancename):
+ retcode = -1
+else:
+ retcode = 0
+</pre></div></div></div></div>
+<div class="section">
+<h2>Action: getConf<a name="Action:_getConf"></a></h2>
+<p>This returns the live client configuration of the cluster -the site-xml file.</p>
+
+<div class="source">
+<pre>getconf --format (xml|properties) --out [outfile]
+</pre></div>
+<p><i>We may want to think hard about whether this is needed</i></p>
+<div class="section">
+<div class="section">
+<h4>Preconditions<a name="Preconditions"></a></h4>
+
+<div class="source">
+<pre>if not slider-instance-live(YARN, instancename) : raise SliderException(EXIT_UNKNOWN_INSTANCE)
+</pre></div></div>
+<div class="section">
+<h4>Postconditions<a name="Postconditions"></a></h4>
+<p>The operation succeeds if the cluster status can be retrieved and saved to the named file/printed to stdout in the format chosen</p>
+
+<div class="source">
+<pre>let status = slider-live-instances(YARN).rpcPort.getJSONClusterStatus()
+let conf = status.clientProperties
+if format == "xml" :
+ let body = status.clientProperties.asXmlDocument()
+else:
+ let body = status.clientProperties.asProperties()
+
+if outfile != "" :
+ data(LocalFS', outfile) == body
+else
+ body in STDOUT'
+</pre></div></div></div></div>
+<div class="section">
+<h2>Action: list<a name="Action:_list"></a></h2>
+
+<div class="source">
+<pre>list [instancename]
+</pre></div>
+<p>Lists all clusters of a user, or only the one given</p>
+<div class="section">
+<div class="section">
+<h4>Preconditions<a name="Preconditions"></a></h4>
+<p>If a instancename is specified it must be in YARNs list of active or completed applications of that user:</p>
+
+<div class="source">
+<pre>if instancename != "" and [] == yarn-application-instances(YARN, instancename, user)
+ raise SliderException(EXIT_UNKNOWN_INSTANCE)
+</pre></div></div>
+<div class="section">
+<h4>Postconditions<a name="Postconditions"></a></h4>
+<p>If no instancename was given, all slider applications of that user are listed, else only the one running (or one of the finished ones)</p>
+
+<div class="source">
+<pre>if instancename == "" :
+ forall a in yarn-application-instances(YARN, user) :
+ a.toString() in STDOUT'
+else
+ let e = yarn-application-instances(YARN, instancename, user)
+ e.toString() in STDOUT'
+</pre></div></div></div></div>
+<div class="section">
+<h2>Action: killcontainer<a name="Action:_killcontainer"></a></h2>
+<p>This is an operation added for testing. It will kill a container in the cluster <i>without flexing the cluster size</i>. As a result, the cluster will detect the failure and attempt to recover from the failure by instantiating a new instance of the cluster</p>
+
+<div class="source">
+<pre>killcontainer cluster --id container-id
+</pre></div>
+<div class="section">
+<div class="section">
+<h4>Preconditions<a name="Preconditions"></a></h4>
+
+<div class="source">
+<pre>if not slider-instance-live(YARN, instancename) : raise SliderException(EXIT_UNKNOWN_INSTANCE)
+
+exists c in slider-app-containers(YARN, instancename, user) where c.id == container-id
+
+let status := AM.getJSONClusterStatus()
+exists role = status.instances where container-id in status.instances[role].values
+</pre></div></div>
+<div class="section">
+<h4>Postconditions<a name="Postconditions"></a></h4>
+<p>The container is not in the list of containers in the cluster</p>
+
+<div class="source">
+<pre>not exists c in containers(YARN) where c.id == container-id
+</pre></div>
+<p>And implicitly, not in the running containers of that application</p>
+
+<div class="source">
+<pre>not exists c in slider-app-containers(YARN', instancename, user) where c.id == container-id
+</pre></div>
+<p>At some time <tt>t1 > t</tt>, the status of the application (<tt>AM'</tt>) will be updated to reflect that YARN has notified the AM of the loss of the container</p>
+
+<div class="source">
+<pre>let status' = AM'.getJSONClusterStatus()
+len(status'.instances[role]) < len(status.instances[role])
+status'.roles[role]["role.failed.instances"] == status'.roles[role]["role.failed.instances"]+1
+</pre></div>
+<p>At some time <tt>t2 > t1</tt> in the future, the size of the containers of the application in the YARN cluster <tt>YARN''</tt> will be as before </p>
+
+<div class="source">
+<pre>let status'' = AM''.getJSONClusterStatus()
+len(status''.instances[r] == len(status.instances[r])
+</pre></div></div></div></div>
+ </div>
+ </div>
+
+ <hr/>
+
+ <footer>
+ <div class="container">
+ <div class="row span12">Copyright © 2014
+ <a href="http://www.apache.org/">The Apache Software Foundation</a>.
+ All Rights Reserved.
+
+ </div>
+
+ <?xml version="1.0" encoding="UTF-8"?>
+<div class="row-fluid">Apache Slider, Slider, Apache, and the Apache Incubator logo are trademarks of The Apache Software Foundation.</div>
+
+ <p id="poweredBy" class="pull-right">
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" />
+ </a>
+ </p>
+
+ </div>
+ </footer>
+ </body>
+</html>
Propchange: incubator/slider/site/content/specification/cli-actions.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/slider/site/content/specification/index.html
URL: http://svn.apache.org/viewvc/incubator/slider/site/content/specification/index.html?rev=1598665&view=auto
==============================================================================
--- incubator/slider/site/content/specification/index.html (added)
+++ incubator/slider/site/content/specification/index.html Fri May 30 16:47:13 2014
@@ -0,0 +1,202 @@
+<!DOCTYPE html>
+<!--
+ | Generated by Apache Maven Doxia at 2014-05-30
+ | Rendered using Apache Maven Fluido Skin 1.3.0
+-->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <meta name="Date-Revision-yyyymmdd" content="20140530" />
+ <meta http-equiv="Content-Language" content="en" />
+ <title>Apache Slider 0.30 (incubating) - </title>
+ <link rel="stylesheet" href="../css/apache-maven-fluido-1.3.0.min.css" />
+ <link rel="stylesheet" href="../css/site.css" />
+ <link rel="stylesheet" href="../css/print.css" media="print" />
+
+
+ <script type="text/javascript" src="../js/apache-maven-fluido-1.3.0.min.js"></script>
+
+
+ </head>
+ <body class="topBarEnabled">
+
+
+
+
+
+ <div id="topbar" class="navbar navbar-fixed-top ">
+ <div class="navbar-inner">
+ <div class="container"><div class="nav-collapse">
+
+
+ <ul class="nav">
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Project Documentation <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li class="dropdown-submenu">
+ <a href="../project-info.html" title="Project Information">Project Information</a>
+ <ul class="dropdown-menu">
+ <li> <a href="../index.html" title="About">About</a>
+</li>
+ <li> <a href="../plugin-management.html" title="Plugin Management">Plugin Management</a>
+</li>
+ <li> <a href="../distribution-management.html" title="Distribution Management">Distribution Management</a>
+</li>
+ <li> <a href="../dependency-info.html" title="Dependency Information">Dependency Information</a>
+</li>
+ <li> <a href="../dependency-convergence.html" title="Dependency Convergence">Dependency Convergence</a>
+</li>
+ <li> <a href="../source-repository.html" title="Source Repository">Source Repository</a>
+</li>
+ <li> <a href="../mail-lists.html" title="Mailing Lists">Mailing Lists</a>
+</li>
+ <li> <a href="../issue-tracking.html" title="Issue Tracking">Issue Tracking</a>
+</li>
+ <li> <a href="../integration.html" title="Continuous Integration">Continuous Integration</a>
+</li>
+ <li> <a href="../plugins.html" title="Project Plugins">Project Plugins</a>
+</li>
+ <li> <a href="../license.html" title="Project License">Project License</a>
+</li>
+ <li> <a href="../modules.html" title="Project Modules">Project Modules</a>
+</li>
+ <li> <a href="../dependency-management.html" title="Dependency Management">Dependency Management</a>
+</li>
+ <li> <a href="../team-list.html" title="Project Team">Project Team</a>
+</li>
+ <li> <a href="../project-summary.html" title="Project Summary">Project Summary</a>
+</li>
+ <li> <a href="../dependencies.html" title="Dependencies">Dependencies</a>
+</li>
+ </ul>
+ </li>
+
+ <li class="dropdown-submenu">
+ <a href="../project-reports.html" title="Project Reports">Project Reports</a>
+ <ul class="dropdown-menu">
+ <li> <a href="../surefire-report.html" title="Surefire Report">Surefire Report</a>
+</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documents <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="../getting_started.html" title="Getting Started">Getting Started</a>
+</li>
+
+ <li> <a href="../manpage.html" title="manpage">manpage</a>
+</li>
+
+ <li> <a href="../troubleshooting.html" title="Troubleshooting">Troubleshooting</a>
+</li>
+
+ <li> <a href="../architecture/index.html" title="Architecture">Architecture</a>
+</li>
+
+ <li> <a href="../developing/index.html" title="Developing">Developing</a>
+</li>
+
+ <li> <a href="../exitcodes.html" title="Exitcodes">Exitcodes</a>
+</li>
+ </ul>
+ </li>
+ </ul>
+
+
+
+
+ </div>
+
+ </div>
+ </div>
+ </div>
+
+ <div class="container">
+ <div id="banner">
+ <div class="pull-left">
+ <a href=".././" id="bannerLeft">
+ <h2>Apache Slider (incubating)</h2>
+ </a>
+ </div>
+ <div class="pull-right"> <div id="bannerRight">
+ <img src="http://incubator.apache.org/images/apache-incubator-logo.png" />
+ </div>
+ </div>
+ <div class="clear"><hr/></div>
+ </div>
+
+ <div id="breadcrumbs">
+ <ul class="breadcrumb">
+
+
+ <li id="publishDate">Last Published: 2014-05-30</li>
+
+
+
+ <li id="projectVersion" class="pull-right">Version: 0.30</li>
+
+ </ul>
+ </div>
+
+
+
+ <div id="bodyColumn" >
+
+ <!-- -
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License. --><h1>Specification of Apache Slider behaviour</h1>
+<p>This is a a “more rigorous” definition of the behavior of Slider in terms of its state and its command-line operations -by defining a ‘formal’ model of HDFS, YARN and Slider’s internal state, then describing the operations that can take place in terms of their preconditions and postconditions.</p>
+<p>This is to show what tests we can create to verify that an action with a valid set of preconditions results in an outcome whose postconditions can be verified. It also makes more apparent what conditions should be expected to result in failures, as well as what the failure codes should be.</p>
+<p>Specifying the behavior has also helped identify areas where there was ambiguity, where clarification and more tests were needed.</p>
+<p>The specification depends on ongoing work in <a class="externalLink" href="https://issues.apache.org/jira/browse/HADOOP-9361">HADOOP-9361</a>: to define the Hadoop Filesytem APIs –This specification uses <a class="externalLink" href="https://github.com/steveloughran/hadoop-trunk/blob/stevel/HADOOP-9361-filesystem-contract/hadoop-common-project/hadoop-common/src/site/markdown/filesystem/notation.md">the same notation</a></p>
+
+<ol style="list-style-type: decimal">
+
+<li><a href="slider-model.html">Model: YARN And Slider</a></li>
+
+<li><a href="cli-actions.html">CLI actions</a></li>
+</ol>
+<p>Exceptions and operations may specify exit codes -these are listed in <a href="../exitcodes.html">Client Exit Codes</a></p>
+ </div>
+ </div>
+
+ <hr/>
+
+ <footer>
+ <div class="container">
+ <div class="row span12">Copyright © 2014
+ <a href="http://www.apache.org/">The Apache Software Foundation</a>.
+ All Rights Reserved.
+
+ </div>
+
+ <?xml version="1.0" encoding="UTF-8"?>
+<div class="row-fluid">Apache Slider, Slider, Apache, and the Apache Incubator logo are trademarks of The Apache Software Foundation.</div>
+
+ <p id="poweredBy" class="pull-right">
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" />
+ </a>
+ </p>
+
+ </div>
+ </footer>
+ </body>
+</html>
Propchange: incubator/slider/site/content/specification/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/slider/site/content/specification/slider-model.html
URL: http://svn.apache.org/viewvc/incubator/slider/site/content/specification/slider-model.html?rev=1598665&view=auto
==============================================================================
--- incubator/slider/site/content/specification/slider-model.html (added)
+++ incubator/slider/site/content/specification/slider-model.html Fri May 30 16:47:13 2014
@@ -0,0 +1,442 @@
+<!DOCTYPE html>
+<!--
+ | Generated by Apache Maven Doxia at 2014-05-30
+ | Rendered using Apache Maven Fluido Skin 1.3.0
+-->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <meta name="Date-Revision-yyyymmdd" content="20140530" />
+ <meta http-equiv="Content-Language" content="en" />
+ <title>Apache Slider 0.30 (incubating) - </title>
+ <link rel="stylesheet" href="../css/apache-maven-fluido-1.3.0.min.css" />
+ <link rel="stylesheet" href="../css/site.css" />
+ <link rel="stylesheet" href="../css/print.css" media="print" />
+
+
+ <script type="text/javascript" src="../js/apache-maven-fluido-1.3.0.min.js"></script>
+
+
+ </head>
+ <body class="topBarEnabled">
+
+
+
+
+
+ <div id="topbar" class="navbar navbar-fixed-top ">
+ <div class="navbar-inner">
+ <div class="container"><div class="nav-collapse">
+
+
+ <ul class="nav">
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Project Documentation <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li class="dropdown-submenu">
+ <a href="../project-info.html" title="Project Information">Project Information</a>
+ <ul class="dropdown-menu">
+ <li> <a href="../index.html" title="About">About</a>
+</li>
+ <li> <a href="../plugin-management.html" title="Plugin Management">Plugin Management</a>
+</li>
+ <li> <a href="../distribution-management.html" title="Distribution Management">Distribution Management</a>
+</li>
+ <li> <a href="../dependency-info.html" title="Dependency Information">Dependency Information</a>
+</li>
+ <li> <a href="../dependency-convergence.html" title="Dependency Convergence">Dependency Convergence</a>
+</li>
+ <li> <a href="../source-repository.html" title="Source Repository">Source Repository</a>
+</li>
+ <li> <a href="../mail-lists.html" title="Mailing Lists">Mailing Lists</a>
+</li>
+ <li> <a href="../issue-tracking.html" title="Issue Tracking">Issue Tracking</a>
+</li>
+ <li> <a href="../integration.html" title="Continuous Integration">Continuous Integration</a>
+</li>
+ <li> <a href="../plugins.html" title="Project Plugins">Project Plugins</a>
+</li>
+ <li> <a href="../license.html" title="Project License">Project License</a>
+</li>
+ <li> <a href="../modules.html" title="Project Modules">Project Modules</a>
+</li>
+ <li> <a href="../dependency-management.html" title="Dependency Management">Dependency Management</a>
+</li>
+ <li> <a href="../team-list.html" title="Project Team">Project Team</a>
+</li>
+ <li> <a href="../project-summary.html" title="Project Summary">Project Summary</a>
+</li>
+ <li> <a href="../dependencies.html" title="Dependencies">Dependencies</a>
+</li>
+ </ul>
+ </li>
+
+ <li class="dropdown-submenu">
+ <a href="../project-reports.html" title="Project Reports">Project Reports</a>
+ <ul class="dropdown-menu">
+ <li> <a href="../surefire-report.html" title="Surefire Report">Surefire Report</a>
+</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documents <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="../getting_started.html" title="Getting Started">Getting Started</a>
+</li>
+
+ <li> <a href="../manpage.html" title="manpage">manpage</a>
+</li>
+
+ <li> <a href="../troubleshooting.html" title="Troubleshooting">Troubleshooting</a>
+</li>
+
+ <li> <a href="../architecture/index.html" title="Architecture">Architecture</a>
+</li>
+
+ <li> <a href="../developing/index.html" title="Developing">Developing</a>
+</li>
+
+ <li> <a href="../exitcodes.html" title="Exitcodes">Exitcodes</a>
+</li>
+ </ul>
+ </li>
+ </ul>
+
+
+
+
+ </div>
+
+ </div>
+ </div>
+ </div>
+
+ <div class="container">
+ <div id="banner">
+ <div class="pull-left">
+ <a href=".././" id="bannerLeft">
+ <h2>Apache Slider (incubating)</h2>
+ </a>
+ </div>
+ <div class="pull-right"> <div id="bannerRight">
+ <img src="http://incubator.apache.org/images/apache-incubator-logo.png" />
+ </div>
+ </div>
+ <div class="clear"><hr/></div>
+ </div>
+
+ <div id="breadcrumbs">
+ <ul class="breadcrumb">
+
+
+ <li id="publishDate">Last Published: 2014-05-30</li>
+
+
+
+ <li id="projectVersion" class="pull-right">Version: 0.30</li>
+
+ </ul>
+ </div>
+
+
+
+ <div id="bodyColumn" >
+
+ <!-- -
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License. --><h1>Formal Apache Slider Model</h1>
+<p>This is the model of Slider and YARN for the rest of the specification.</p>
+<div class="section">
+<h2>File System<a name="File_System"></a></h2>
+<p>A File System <tt>HDFS</tt> represents a Hadoop FileSystem -either HDFS or another File System which spans the cluster. There are also other filesystems that can act as sources of data that is then copied into HDFS. These will be marked as <tt>FS</tt> or with the generic <tt>FileSystem</tt> type.</p>
+<p>There’s ongoing work in <a class="externalLink" href="https://issues.apache.org/jira/browse/HADOOP-9361">HADOOP-9361</a> to define the Hadoop Filesytem APIs using the same notation as here, the latest version being available on <a class="externalLink" href="https://github.com/steveloughran/hadoop-trunk/tree/stevel/HADOOP-9361-filesystem-contract/hadoop-common-project/hadoop-common/src/site/markdown/filesystem">github</a> Two key references are</p>
+
+<ol style="list-style-type: decimal">
+
+<li><a class="externalLink" href="https://github.com/steveloughran/hadoop-trunk/blob/stevel/HADOOP-9361-filesystem-contract/hadoop-common-project/hadoop-common/src/site/markdown/filesystem/notation.md">The notation reused in the Slider specifications</a></li>
+
+<li><a class="externalLink" href="https://github.com/steveloughran/hadoop-trunk/blob/stevel/HADOOP-9361-filesystem-contract/hadoop-common-project/hadoop-common/src/site/markdown/filesystem/model.md">The model of the filesystem</a></li>
+</ol>
+<p>The model and its predicates and invariants will be used in these specifications.</p></div>
+<div class="section">
+<h2>YARN<a name="YARN"></a></h2>
+<p>From the perspective of YARN application, The YARN runtime is a state, <tt>YARN</tt>, comprised of: <tt>(Apps, Queues, Nodes)</tt></p>
+
+<div class="source">
+<pre>Apps: Map[AppId, ApplicationReport]
+</pre></div>
+<p>An application has a name, an application report and a list of outstanding requests</p>
+
+<div class="source">
+<pre>App: (Name, report: ApplicationReport, Requests:List[AmRequest])
+</pre></div>
+<p>An application report contains a mixture of static and dynamic state of the application and the AM.</p>
+
+<div class="source">
+<pre>ApplicationReport: AppId, Type, User, YarnApplicationState, AmContainer, RpcPort, TrackingURL,
+</pre></div>
+<p>YARN applications have a number of states. These are ordered such that if the <tt>state.ordinal() > RUNNING.ordinal()</tt> then the application has entered an exit state.</p>
+
+<div class="source">
+<pre>YarnApplicationState : [NEW, NEW_SAVING, SUBMITTED, ACCEPTED, RUNNING, FINISHED, FAILED, KILLED ]
+</pre></div>
+<p>AMs can request containers to be added or released </p>
+
+<div class="source">
+<pre>AmRequest = { add-container(priority, requirements), release(containerId)}
+</pre></div>
+<p>Job queues are named queues of job requests; there is always a queue called <tt>"default"</tt></p>
+
+<div class="source">
+<pre>Queues: Map[String:Queue]
+ Queue: List[Requests]
+ Request = {
+ launch(app-name, app-type, requirements, context)
+ }
+ Context: (localized-resources: Map[String,URL], command)
+</pre></div>
+<p>This is doesn’t completely model the cluster from the AM perspective -there’s no notion of node operations (launching code in a container) or events coming from YARN.</p>
+<p>The <tt>Nodes</tt> structure models the nodes in a cluster</p>
+
+<div class="source">
+<pre>Nodes: Map[nodeID,(name, containers:List[Container])]
+</pre></div>
+<p>A container contains some state</p>
+
+<div class="source">
+<pre>Container: (containerId, appId, context)
+</pre></div>
+<p>The containers in a cluster are the aggregate set of all containers across all nodes</p>
+
+<div class="source">
+<pre>def containers(YARN) =
+ [c for n in keys(YARN.Nodes) for c in YARN.Nodes[n].Containers ]
+</pre></div>
+<p>The containers of an application are all containers that are considered owned by it,</p>
+
+<div class="source">
+<pre>def app-containers(YARN, appId: AppId) =
+ [c in containers(YARN) where c.appId == appId ]
+</pre></div>
+<div class="section">
+<h3>Operations & predicates used the specifications<a name="Operations__predicates_used_the_specifications"></a></h3>
+
+<div class="source">
+<pre>def applications(YARN, type) =
+ [ app.report for app in YARN.Apps.values where app.report.Type == type]
+
+def user-applications(YARN, type, user)
+ [a in applications(YARN, type) where: a.User == user]
+</pre></div></div></div>
+<div class="section">
+<h2>UserGroupInformation<a name="UserGroupInformation"></a></h2>
+<p>Applications are launched and executed on hosts computers: either client machines or nodes in the cluster, these have their own state which may need modeling</p>
+
+<div class="source">
+<pre>HostState: Map[String, String]
+</pre></div>
+<p>A key part of the host state is actually the identity of the current user, which is used to define the location of the persistent state of the cluster -including its data, and the identity under which a deployed container executes.</p>
+<p>In a secure cluster, this identity is accompanied by kerberos tokens that grant the caller access to the filesystem and to parts of YARN itself.</p>
+<p>This specification does not currently explicitly model the username and credentials. If it did they would be used throughout the specification to bind to a YARN or HDFS instance.</p>
+<p><tt>UserGroupInformation.getCurrentUser(): UserGroupInformation</tt></p>
+<p>Returns the current user information. This information is immutable and fixed for the duration of the process.</p></div>
+<div class="section">
+<h2>Slider Model<a name="Slider_Model"></a></h2>
+<div class="section">
+<h3>Cluster name<a name="Cluster_name"></a></h3>
+<p>A valid cluster name is a name of length > 1 which follows the internet hostname scheme of letter followed by letter or digit</p>
+
+<div class="source">
+<pre>def valid-cluster-name(c) =
+ len(c)> 0
+ and c[0] in ['a'..'z']
+ and c[1] in (['a'..'z'] + ['-'] + ['0..9'])
+</pre></div></div>
+<div class="section">
+<h3>Persistent Cluster State<a name="Persistent_Cluster_State"></a></h3>
+<p>A Slider cluster’s persistent state is stored in a path</p>
+
+<div class="source">
+<pre>def cluster-path(FS, clustername) = user-home(FS) + ["clusters", clustername]
+def cluster-json-path(FS, clustername) = cluster-path(FS, clustername) + ["cluster.json"]
+def original-conf-path(FS, clustername) = cluster-path(FS, clustername) + ["original"]
+def generated-conf-path(FS, clustername) = cluster-path(FS, clustername) + ["generated"]
+def data-path(FS, clustername) = cluster-path(FS, clustername) + ["data"]
+</pre></div>
+<p>When a cluster is built/created the specified original configuration directory is copied to <tt>original-conf-path(FS, clustername)</tt>; this is patched for the specific instance bindings and saved into <tt>generated-conf-path(FS, clustername)</tt>.</p>
+<p>A cluster <i>exists</i> if all of these paths are found:</p>
+
+<div class="source">
+<pre>def cluster-exists(FS, clustername) =
+ is-dir(FS, cluster-path(FS, clustername))
+ and is-file(FS, cluster-json-path(FS, clustername))
+ and is-dir(FS, original-conf-path(FS, clustername))
+ and generated-conf-path(FS, original-conf-path(FS, clustername))
+</pre></div>
+<p>A cluster is considered <tt>running</tt> if there is a Slider application type belonging to the current user in one of the states <tt>{NEW, NEW_SAVING, SUBMITTED, ACCEPTED, RUNNING}</tt>. </p>
+
+<div class="source">
+<pre>def final-yarn-states = {FINISHED, FAILED, KILLED }
+
+def slider-app-instances(YARN, clustername, user) =
+ [a in user-applications(YARN, "slider", user) where:
+ and a.Name == clustername]
+
+def slider-app-running-instances(YARN, clustername, user) =
+ [a in slider-app-instances(YARN, user, clustername) where:
+ not a.YarnApplicationState in final-yarn-state]
+
+def slider-app-running(YARN, clustername, user) =
+ [] != slider-app-running-instances(YARN, clustername, user)
+
+def slider-app-live-instances(YARN, clustername, user) =
+ [a in slider-app-instances(YARN, user, clustername) where:
+ a.YarnApplicationState == RUNNING]
+
+def slider-app-live(YARN, clustername, user) =
+ [] != slider-app-live-instances(YARN, clustername, user)
+</pre></div></div>
+<div class="section">
+<h3>Invariant: there must never be more than one running instance of a named Slider cluster<a name="Invariant:_there_must_never_be_more_than_one_running_instance_of_a_named_Slider_cluster"></a></h3>
+<p>There must never be more than one instance of the same Slider cluster running:</p>
+
+<div class="source">
+<pre>forall a in user-applications(YARN, "slider", user):
+ len(slider-app-running-instances(YARN, a.Name, user)) <= 1
+</pre></div>
+<p>There may be multiple instances in a finished state, and one running instance alongside multiple finished instances -the applications that work with Slider MUST select a running cluster ahead of any terminated clusters.</p></div>
+<div class="section">
+<h3>Containers of an application<a name="Containers_of_an_application"></a></h3>
+<p>The containers of a slider application are the set of containers of that application</p>
+
+<div class="source">
+<pre>def slider-app-containers(YARN, clustername, user) =
+ app-containers(YARN, appid where
+ appid = slider-app-running-instances(YARN, clustername, user)[0])
+</pre></div></div>
+<div class="section">
+<h3>RPC Access to a slider cluster<a name="RPC_Access_to_a_slider_cluster"></a></h3>
+<p>An application is accepting RPC requests for a given protocol if there is a port binding defined and it is possible to authenticate a connection using the specified protocol</p>
+
+<div class="source">
+<pre> def rpc-connection(appReport, protocol) =
+ appReport.host != null
+ appReport.rpcPort != 0
+ and RPC.getProtocolProxy(appReport.host, appReport.rpcPort, protocol)
+</pre></div>
+<p>Being able to open an RPC port is the strongest definition of liveness possible to make: if the AM responds to RPC operations, it is doing useful work.</p></div>
+<div class="section">
+<h3>Valid Cluster Description<a name="Valid_Cluster_Description"></a></h3>
+<p>The <tt>cluster.json</tt> file of a cluster configures Slider to deploy the application. </p>
+<div class="section">
+<h4>well-defined-cluster(cluster-description)<a name="well-defined-clustercluster-description"></a></h4>
+<p>A Cluster Description is well-defined if it is valid JSON and required properties are present</p>
+<p><b>OBSOLETE</b></p>
+<p>Irrespective of specific details for deploying the Slider AM or any provider-specific role instances, a Cluster Description defined in a <tt>cluster.json</tt> file at the path <tt>cluster-json-path(FS, clustername)</tt> is well-defined if</p>
+
+<ol style="list-style-type: decimal">
+
+<li>It is parseable by the jackson JSON parser.</li>
+
+<li>Root elements required of a Slider cluster specification must be defined, and, where appropriate, non-empty</li>
+
+<li>It contains the extensible elements required of a Slider cluster specification. For example, <tt>options</tt> and <tt>roles</tt></li>
+
+<li>The types of the extensible elements match those expected by Slider.</li>
+
+<li>The <tt>version</tt> element matches a supported version</li>
+
+<li>Exactly one of <tt>options/cluster.application.home</tt> and <tt>options/cluster.application.image.path</tt> must exist.</li>
+
+<li>Any cluster options that are required to be integers must be integers</li>
+</ol>
+<p>This specification is very vague here to avoid duplication: the cluster description structure is currently implicitly defined in <tt>org.apache.slider.api.ClusterDescription</tt> </p>
+<p>Currently Slider ignores unknown elements during parsing. This may be changed.</p>
+<p>The test for this state does not refer to the cluster filesystem</p></div>
+<div class="section">
+<h4>deployable-cluster(FS, cluster-description)<a name="deployable-clusterFS_cluster-description"></a></h4>
+<p>A Cluster Description defines a deployable cluster if it is well-defined cluster and the contents contain valid information to deploy a cluster</p>
+<p>This defines how a cluster description is valid in the extends the valid configuration with </p>
+
+<ul>
+
+<li>The entry <tt>name</tt> must match a supported provider</li>
+
+<li>
+<p>Any elements that name the cluster match the cluster name as defined by the path to the cluster:</p>
+
+<div class="source">
+<pre>originConfigurationPath == original-conf-path(FS, clustername)
+generatedConfigurationPath == generated-conf-path(FS, clustername)
+dataPath == data-path(FS, clustername)
+</pre></div></li>
+
+<li>
+<p>The paths defined in <tt>originConfigurationPath</tt> , <tt>generatedConfigurationPath</tt> and <tt>dataPath</tt> must all exist.</p></li>
+
+<li><tt>options/zookeeper.path</tt> must be defined and refer to a path in the ZK cluster defined by (<tt>options/zookeeper.hosts</tt>, <tt>zookeeper.port)</tt> to which the user has write access (required by HBase and Accumulo)</li>
+
+<li>If <tt>options/cluster.application.image.path</tt> is defined, it must exist and be readable by the user.</li>
+
+<li>
+<p>It must declare a type that maps to a provider entry in the Slider client’s XML configuration:</p>
+
+<div class="source">
+<pre>len(clusterspec["type"]) > 0
+clientconfig["slider.provider."+ clusterspec["type"]] != null
+</pre></div></li>
+
+<li>
+<p>That entry must map to a class on the classpath which can be instantiated and cast to <tt>SliderProviderFactory</tt>.</p>
+
+<div class="source">
+<pre>let classname = clientconfig["slider.provider."+ clusterspec["type"]]
+(Class.forName(classname).newInstance()) instanceof SliderProviderFactory
+</pre></div></li>
+</ul></div>
+<div class="section">
+<h4>valid-for-provider(cluster-description, provider)<a name="valid-for-providercluster-description_provider"></a></h4>
+<p>A provider considers a specification valid if its own validation logic is satisfied. This normally consists of rules about the number of instances of different roles; it may include other logic.</p></div></div></div>
+ </div>
+ </div>
+
+ <hr/>
+
+ <footer>
+ <div class="container">
+ <div class="row span12">Copyright © 2014
+ <a href="http://www.apache.org/">The Apache Software Foundation</a>.
+ All Rights Reserved.
+
+ </div>
+
+ <?xml version="1.0" encoding="UTF-8"?>
+<div class="row-fluid">Apache Slider, Slider, Apache, and the Apache Incubator logo are trademarks of The Apache Software Foundation.</div>
+
+ <p id="poweredBy" class="pull-right">
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" />
+ </a>
+ </p>
+
+ </div>
+ </footer>
+ </body>
+</html>
Propchange: incubator/slider/site/content/specification/slider-model.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/slider/site/content/surefire-report.html
URL: http://svn.apache.org/viewvc/incubator/slider/site/content/surefire-report.html?rev=1598665&view=auto
==============================================================================
--- incubator/slider/site/content/surefire-report.html (added)
+++ incubator/slider/site/content/surefire-report.html Fri May 30 16:47:13 2014
@@ -0,0 +1,212 @@
+<!DOCTYPE html>
+<!--
+ | Generated by Apache Maven Doxia at 2014-05-30
+ | Rendered using Apache Maven Fluido Skin 1.3.0
+-->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <meta name="Date-Revision-yyyymmdd" content="20140530" />
+ <meta http-equiv="Content-Language" content="en" />
+ <title>Apache Slider 0.30 (incubating) - Surefire Report</title>
+ <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
+ <link rel="stylesheet" href="./css/site.css" />
+ <link rel="stylesheet" href="./css/print.css" media="print" />
+
+
+ <script type="text/javascript" src="./js/apache-maven-fluido-1.3.0.min.js"></script>
+
+
+ </head>
+ <body class="topBarEnabled">
+
+
+
+
+
+ <div id="topbar" class="navbar navbar-fixed-top ">
+ <div class="navbar-inner">
+ <div class="container"><div class="nav-collapse">
+
+
+ <ul class="nav">
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Project Documentation <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li class="dropdown-submenu">
+ <a href="project-info.html" title="Project Information">Project Information</a>
+ <ul class="dropdown-menu">
+ <li> <a href="index.html" title="About">About</a>
+</li>
+ <li> <a href="plugin-management.html" title="Plugin Management">Plugin Management</a>
+</li>
+ <li> <a href="distribution-management.html" title="Distribution Management">Distribution Management</a>
+</li>
+ <li> <a href="dependency-info.html" title="Dependency Information">Dependency Information</a>
+</li>
+ <li> <a href="dependency-convergence.html" title="Dependency Convergence">Dependency Convergence</a>
+</li>
+ <li> <a href="source-repository.html" title="Source Repository">Source Repository</a>
+</li>
+ <li> <a href="mail-lists.html" title="Mailing Lists">Mailing Lists</a>
+</li>
+ <li> <a href="issue-tracking.html" title="Issue Tracking">Issue Tracking</a>
+</li>
+ <li> <a href="integration.html" title="Continuous Integration">Continuous Integration</a>
+</li>
+ <li> <a href="plugins.html" title="Project Plugins">Project Plugins</a>
+</li>
+ <li> <a href="license.html" title="Project License">Project License</a>
+</li>
+ <li> <a href="modules.html" title="Project Modules">Project Modules</a>
+</li>
+ <li> <a href="dependency-management.html" title="Dependency Management">Dependency Management</a>
+</li>
+ <li> <a href="team-list.html" title="Project Team">Project Team</a>
+</li>
+ <li> <a href="project-summary.html" title="Project Summary">Project Summary</a>
+</li>
+ <li> <a href="dependencies.html" title="Dependencies">Dependencies</a>
+</li>
+ </ul>
+ </li>
+
+ <li class="dropdown-submenu">
+ <a href="project-reports.html" title="Project Reports">Project Reports</a>
+ <ul class="dropdown-menu">
+ <li> <a href="surefire-report.html" title="Surefire Report">Surefire Report</a>
+</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documents <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="getting_started.html" title="Getting Started">Getting Started</a>
+</li>
+
+ <li> <a href="manpage.html" title="manpage">manpage</a>
+</li>
+
+ <li> <a href="troubleshooting.html" title="Troubleshooting">Troubleshooting</a>
+</li>
+
+ <li> <a href="architecture/index.html" title="Architecture">Architecture</a>
+</li>
+
+ <li> <a href="developing/index.html" title="Developing">Developing</a>
+</li>
+
+ <li> <a href="exitcodes.html" title="Exitcodes">Exitcodes</a>
+</li>
+ </ul>
+ </li>
+ </ul>
+
+
+
+
+ </div>
+
+ </div>
+ </div>
+ </div>
+
+ <div class="container">
+ <div id="banner">
+ <div class="pull-left">
+ <a href="./" id="bannerLeft">
+ <h2>Apache Slider (incubating)</h2>
+ </a>
+ </div>
+ <div class="pull-right"> <div id="bannerRight">
+ <img src="http://incubator.apache.org/images/apache-incubator-logo.png" />
+ </div>
+ </div>
+ <div class="clear"><hr/></div>
+ </div>
+
+ <div id="breadcrumbs">
+ <ul class="breadcrumb">
+
+
+ <li id="publishDate">Last Published: 2014-05-30</li>
+
+
+
+ <li id="projectVersion" class="pull-right">Version: 0.30</li>
+
+ </ul>
+ </div>
+
+
+
+ <div id="bodyColumn" >
+
+ <script type="text/javascript">
+//<![CDATA[
+function toggleDisplay(elementId) {
+ var elm = document.getElementById(elementId + 'error');
+ if (elm && typeof elm.style != "undefined") {
+ if (elm.style.display == "none") {
+ elm.style.display = "";
+ document.getElementById(elementId + 'off').style.display = "none";
+ document.getElementById(elementId + 'on').style.display = "inline";
+ } else if (elm.style.display == "") { elm.style.display = "none";
+ document.getElementById(elementId + 'off').style.display = "inline";
+ document.getElementById(elementId + 'on').style.display = "none";
+ }
+ }
+ }
+//]]>
+</script>
+<div class="section">
+<h2>Surefire Report<a name="Surefire_Report"></a></h2></div>
+<div class="section">
+<h2>Summary<a name="Summary"></a></h2><a name="Summary"></a><br />
+<table border="1" class="table table-striped">
+<tr class="a">
+<th>Tests</th>
+<th>Errors </th>
+<th>Failures</th>
+<th>Skipped</th>
+<th>Success Rate</th>
+<th>Time</th></tr>
+<tr class="b">
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0%</td>
+<td>0</td></tr></table><br />
+<p>Note: failures are anticipated and checked for with assertions while errors are unanticipated.</p><br /></div>
+ </div>
+ </div>
+
+ <hr/>
+
+ <footer>
+ <div class="container">
+ <div class="row span12">Copyright © 2014
+ <a href="http://www.apache.org/">The Apache Software Foundation</a>.
+ All Rights Reserved.
+
+ </div>
+
+ <?xml version="1.0" encoding="UTF-8"?>
+<div class="row-fluid">Apache Slider, Slider, Apache, and the Apache Incubator logo are trademarks of The Apache Software Foundation.</div>
+
+ <p id="poweredBy" class="pull-right">
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" />
+ </a>
+ </p>
+
+ </div>
+ </footer>
+ </body>
+</html>
Propchange: incubator/slider/site/content/surefire-report.html
------------------------------------------------------------------------------
svn:eol-style = native