helix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ka...@apache.org
Subject [01/31] Redesign documentation for 0.6.2, 0.7.0, and trunk
Date Thu, 02 Jan 2014 00:14:01 GMT
Updated Branches:
  refs/heads/helix-website 92edaabc1 -> bea210200


http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/4a4510d1/site-releases/trunk/src/site/markdown/tutorial_user_def_rebalancer.md
----------------------------------------------------------------------
diff --git a/site-releases/trunk/src/site/markdown/tutorial_user_def_rebalancer.md b/site-releases/trunk/src/site/markdown/tutorial_user_def_rebalancer.md
index 6246f68..551f2ec 100644
--- a/site-releases/trunk/src/site/markdown/tutorial_user_def_rebalancer.md
+++ b/site-releases/trunk/src/site/markdown/tutorial_user_def_rebalancer.md
@@ -21,7 +21,7 @@ under the License.
   <title>Tutorial - User-Defined Rebalancing</title>
 </head>
 
-# [Helix Tutorial](./Tutorial.html): User-Defined Rebalancing
+## [Helix Tutorial](./Tutorial.html): User-Defined Rebalancing
 
 Even though Helix can compute both the location and the state of replicas internally using
a default fully-automatic rebalancer, specific applications may require rebalancing strategies
that optimize for different requirements. Thus, Helix allows applications to plug in arbitrary
rebalancer algorithms that implement a provided interface. One of the main design goals of
Helix is to provide maximum flexibility to any distributed application. Thus, it allows applications
to fully implement the rebalancer, which is the core constraint solver in the system, if the
application developer so chooses.
 
@@ -30,33 +30,35 @@ Whenever the state of the cluster changes, as is the case when participants
join
 The [HelixRebalancer](http://helix.incubator.apache.org/apidocs/reference/org/apache/helix/controller/rebalancer/HelixRebalancer.html)
interface is as follows:
 
 ```
-public void init(HelixManager helixManager);
+public void init(HelixManager helixManager, ControllerContextProvider contextProvider);
 
 public ResourceAssignment computeResourceMapping(RebalancerConfig rebalancerConfig, Cluster
cluster,
     ResourceCurrentState currentState);
 ```
+The `init` method is called exactly once per resource, and allows the rebalancer to save
the connection and a class that can persist and retrieve arbitrary contexts across controller
pipeline runs.
+
 The first parameter is a configuration of the resource to rebalance, the second is a full
cache of all of the cluster data available to Helix, and the third is a snapshot of the actual
current placements and state assignments. From the cluster variable, it is also possible to
access the ResourceAssignment last generated by this rebalancer. Internally, Helix implements
the same interface for its own rebalancing routines, so a user-defined rebalancer will be
cognizant of the same information about the cluster as an internal implementation. Helix strives
to provide applications the ability to implement algorithms that may require a large portion
of the entire state of the cluster to make the best placement and state assignment decisions
possible.
 
 A ResourceAssignment is a full representation of the location and the state of each replica
of each partition of a given resource. This is a simple representation of the placement that
the algorithm believes is the best possible. If the placement meets all defined constraints,
this is what will become the actual state of the distributed system.
 
-### Rebalancer Context
+### Rebalancer Config
 
-Helix provides an interface called [RebalancerContext](http://helix.incubator.apache.org/apidocs/reference/org/apache/helix/controller/rebalancer/context/RebalancerContext.html).
For each of the four main [rebalancing modes](./tutorial_rebalance.html), there is a base
class called [PartitionedRebalancerContext](http://helix.incubator.apache.org/apidocs/reference/org/apache/helix/controller/rebalancer/context/PartitionedRebalancerContext.html),
which contains all of the basic properties required for a partitioned resource. Helix provides
three derived classes for PartitionedRebalancerContext: FullAutoRebalancerContext, SemiAutoRebalancerContext,
and CustomizedRebalancerContext. If none of these work for your application, you can create
your own class that derives PartiitonedRebalancerContext (or even only implements RebalancerContext).
+Helix provides an interface called [RebalancerConfig](http://helix.incubator.apache.org/apidocs/reference/org/apache/helix/controller/rebalancer/config/RebalancerConfig.html).
For each of the four main [rebalancing modes](./tutorial_rebalance.html), there is a base
class called [PartitionedRebalancerConfig](http://helix.incubator.apache.org/apidocs/reference/org/apache/helix/controller/rebalancer/config/PartitionedRebalancerConfig.html),
which contains all of the basic properties required for a partitioned resource. Helix provides
three derived classes for PartitionedRebalancerConfig: FullAutoRebalancerConfig, SemiAutoRebalancerConfig,
and CustomizedRebalancerConfig. If none of these work for your application, you can create
your own class that derives PartiitonedRebalancerConfig (or even only implements RebalancerConfig).
 
 ### Specifying a Rebalancer
 
 #### Using Logical Accessors
-To specify the rebalancer, one can use ```PartitionedRebalancerContext#setRebalancerRef(RebalancerRef)```
to specify the specific implementation of the rebalancerClass. For example, here's a base
constructed PartitionedRebalancerContext with a user-specified class:
+To specify the rebalancer, one can use ```PartitionedRebalancerConfig#setRebalancerRef(RebalancerRef)```
to specify the specific implementation of the rebalancerClass. For example, here's a base
constructed PartitionedRebalancerConfig with a user-specified class:
 
 ```
 RebalancerRef rebalancerRef = RebalancerRef.from(className);
-PartitionedRebalancerContext rebalanceContext =
-    new PartitionedRebalancerContext.Builder(resourceId).replicaCount(1).addPartition(partition1)
+PartitionedRebalancerConfig rebalanceConfig =
+    new PartitionedRebalancerConfig.Builder(resourceId).replicaCount(1).addPartition(partition1)
         .addPartition(partition2).stateModelDefId(stateModelDef.getStateModelDefId())
         .rebalancerRef(rebalancerRef).build();
 ```
 
-The class name is a fully-qualified class name consisting of its package and its name, and
the class should implement the Rebalancer interface. Now, the context can be added to a ResourceConfig
through ```ResourceConfig.Builder#rebalancerContext(RebalancerContext)``` and the context
will automatically be made available to the rebalancer for all subsequent executions.
+The class name is a fully-qualified class name consisting of its package and its name, and
the class should implement the Rebalancer interface. Now, the config can be added to a ResourceConfig
through ```ResourceConfig.Builder#rebalancerConfig(RebalancerConfig)``` and the config will
automatically be made available to the rebalancer for all subsequent executions.
 
 #### Using HelixAdmin
 For implementations that set up the cluster through existing code, the following HelixAdmin
calls will update the Rebalancer class:
@@ -89,21 +91,25 @@ Consider the case where partitions are locks in a lock manager and 6 locks
are t
 
 ```
 @Override
-public ResourceAssignment computeResourceMapping(RebalancerConfig rebalancerConfig, Cluster
cluster,
-    ResourceCurrentState currentState) {
-  // Get the rebalcancer context (a basic partitioned one)
-  PartitionedRebalancerContext context = rebalancerConfig.getRebalancerContext(
-      PartitionedRebalancerContext.class);
+public void init(HelixManager manager, ControllerContextProvider contextProvider) {
+  // do nothing; this rebalancer is independent of the manager
+}
+
+@Override
+public ResourceAssignment computeResourceMapping(RebalancerConfig rebalancerConfig,
+    ResourceAssignment prevAssignment, Cluster cluster, ResourceCurrentState currentState)
{
+  // get a typed config
+  PartitionedRebalancerConfig config = PartitionedRebalancerConfig.from(rebalancerConfig);
 
   // Initialize an empty mapping of locks to participants
-  ResourceAssignment assignment = new ResourceAssignment(context.getResourceId());
+  ResourceAssignment assignment = new ResourceAssignment(config.getResourceId());
 
   // Get the list of live participants in the cluster
-  List<ParticipantId> liveParticipants = new ArrayList<ParticipantId>(
-      cluster.getLiveParticipantMap().keySet());
+  List<ParticipantId> liveParticipants =
+      new ArrayList<ParticipantId>(cluster.getLiveParticipantMap().keySet());
 
   // Get the state model (should be a simple lock/unlock model) and the highest-priority
state
-  StateModelDefId stateModelDefId = context.getStateModelDefId();
+  StateModelDefId stateModelDefId = config.getStateModelDefId();
   StateModelDefinition stateModelDef = cluster.getStateModelMap().get(stateModelDefId);
   if (stateModelDef.getStatesPriorityList().size() < 1) {
     LOG.error("Invalid state model definition. There should be at least one state.");
@@ -129,7 +135,7 @@ public ResourceAssignment computeResourceMapping(RebalancerConfig rebalancerConf
   // This assumes a simple lock-unlock model where the only state of interest is which nodes
have
   // acquired each lock.
   int i = 0;
-  for (PartitionId partition : context.getPartitionSet()) {
+  for (PartitionId partition : config.getPartitionSet()) {
     Map<ParticipantId, State> replicaMap = new HashMap<ParticipantId, State>();
     for (int j = i; j < i + lockHolders; j++) {
       int participantIndex = j % liveParticipants.size();
@@ -224,4 +230,4 @@ On any node failure, as in the case of node addition, the rebalancer is
invoked
 The rebalancer was invoked once again and the resulting ResourceAssignment reflects the steady
state.
 
 ### Caveats
-- The rebalancer class must be available at runtime, or else Helix will not attempt to rebalance
at all
\ No newline at end of file
+- The rebalancer class must be available at runtime, or else Helix will not attempt to rebalance
at all

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/4a4510d1/site-releases/trunk/src/site/markdown/tutorial_yaml.md
----------------------------------------------------------------------
diff --git a/site-releases/trunk/src/site/markdown/tutorial_yaml.md b/site-releases/trunk/src/site/markdown/tutorial_yaml.md
index 0f8e0cc..4660afa 100644
--- a/site-releases/trunk/src/site/markdown/tutorial_yaml.md
+++ b/site-releases/trunk/src/site/markdown/tutorial_yaml.md
@@ -21,7 +21,7 @@ under the License.
   <title>Tutorial - YAML Cluster Setup</title>
 </head>
 
-# [Helix Tutorial](./Tutorial.html): YAML Cluster Setup
+## [Helix Tutorial](./Tutorial.html): YAML Cluster Setup
 
 As an alternative to using Helix Admin to set up the cluster, its resources, constraints,
and the state model, Helix supports bootstrapping a cluster configuration based on a YAML
file. Below is an annotated example of such a file for a simple distributed lock manager where
a lock can only be LOCKED or RELEASED, and each lock only allows a single participant to hold
it in the LOCKED state.
 
@@ -99,4 +99,4 @@ Some notes:
 
 - A rebalancer class is only required for the USER_DEFINED mode. It is ignored otherwise.
 
-- Built-in state models, like OnlineOffline, LeaderStandby, and MasterSlave, or state models
that have already been added only require a name for stateModel. If partition and/or replica
counts are not provided, a value of 1 is assumed.
\ No newline at end of file
+- Built-in state models, like OnlineOffline, LeaderStandby, and MasterSlave, or state models
that have already been added only require a name for stateModel. If partition and/or replica
counts are not provided, a value of 1 is assumed.

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/4a4510d1/site-releases/trunk/src/site/resources/images/HELIX-components.png
----------------------------------------------------------------------
diff --git a/site-releases/trunk/src/site/resources/images/HELIX-components.png b/site-releases/trunk/src/site/resources/images/HELIX-components.png
deleted file mode 100644
index c0c35ae..0000000
Binary files a/site-releases/trunk/src/site/resources/images/HELIX-components.png and /dev/null
differ

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/4a4510d1/site-releases/trunk/src/site/resources/images/bootstrap_statemodel.gif
----------------------------------------------------------------------
diff --git a/site-releases/trunk/src/site/resources/images/bootstrap_statemodel.gif b/site-releases/trunk/src/site/resources/images/bootstrap_statemodel.gif
deleted file mode 100644
index b8f8a42..0000000
Binary files a/site-releases/trunk/src/site/resources/images/bootstrap_statemodel.gif and
/dev/null differ

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/4a4510d1/site-releases/trunk/src/site/resources/images/helix-architecture.png
----------------------------------------------------------------------
diff --git a/site-releases/trunk/src/site/resources/images/helix-architecture.png b/site-releases/trunk/src/site/resources/images/helix-architecture.png
deleted file mode 100644
index 6f69a2d..0000000
Binary files a/site-releases/trunk/src/site/resources/images/helix-architecture.png and /dev/null
differ

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/4a4510d1/site-releases/trunk/src/site/resources/images/helix-logo.jpg
----------------------------------------------------------------------
diff --git a/site-releases/trunk/src/site/resources/images/helix-logo.jpg b/site-releases/trunk/src/site/resources/images/helix-logo.jpg
deleted file mode 100644
index d6428f6..0000000
Binary files a/site-releases/trunk/src/site/resources/images/helix-logo.jpg and /dev/null
differ

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/4a4510d1/site-releases/trunk/src/site/resources/images/helix-znode-layout.png
----------------------------------------------------------------------
diff --git a/site-releases/trunk/src/site/resources/images/helix-znode-layout.png b/site-releases/trunk/src/site/resources/images/helix-znode-layout.png
deleted file mode 100644
index 5bafc45..0000000
Binary files a/site-releases/trunk/src/site/resources/images/helix-znode-layout.png and /dev/null
differ

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/4a4510d1/site-releases/trunk/src/site/resources/images/statemachine.png
----------------------------------------------------------------------
diff --git a/site-releases/trunk/src/site/resources/images/statemachine.png b/site-releases/trunk/src/site/resources/images/statemachine.png
deleted file mode 100644
index 43d27ec..0000000
Binary files a/site-releases/trunk/src/site/resources/images/statemachine.png and /dev/null
differ

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/4a4510d1/site-releases/trunk/src/site/resources/images/system.png
----------------------------------------------------------------------
diff --git a/site-releases/trunk/src/site/resources/images/system.png b/site-releases/trunk/src/site/resources/images/system.png
deleted file mode 100644
index f8a05c8..0000000
Binary files a/site-releases/trunk/src/site/resources/images/system.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/4a4510d1/site-releases/trunk/src/site/site.xml
----------------------------------------------------------------------
diff --git a/site-releases/trunk/src/site/site.xml b/site-releases/trunk/src/site/site.xml
index f2851a1..90f88d6 100644
--- a/site-releases/trunk/src/site/site.xml
+++ b/site-releases/trunk/src/site/site.xml
@@ -17,12 +17,12 @@
 -->
 <project name="Apache Helix">
   <bannerLeft>
-    <src>images/helix-logo.jpg</src>
-    <href>http://helix.incubator.apache.org/site-releases/0.7.0-incubating-site</href>
+    <src>../../images/helix-logo.jpg</src>
+    <href>http://helix.incubator.apache.org/</href>
   </bannerLeft>
   <bannerRight>
-    <src>http://incubator.apache.org/images/egg-logo.png</src>
-    <href>http://incubator.apache.org/</href>
+    <src>../../images/feather_small.gif</src>
+    <href>http://www.apache.org/</href>
   </bannerRight>
   <version position="none"/>
 
@@ -58,17 +58,18 @@
       <item name="trunk" href="http://helix.incubator.apache.org/site-releases/trunk-site/"/>
     </breadcrumbs>
 
-    <menu name="Apache Helix">
-      <item name="Home" href="../../index.html"/>
+    <links>
+      <item name="Helix trunk" href="./index.html"/>
+    </links>
+
+    <menu name="Get Helix">
+      <item name="Building" href="./Building.html"/>
     </menu>
 
-    <menu name="Helix Trunk">
-      <item name="Introduction" href="./index.html"/>
-      <item name="Getting Helix" href="./Building.html"/>
-      <item name="Core concepts" href="./Concepts.html"/>
-      <item name="Architecture" href="./Architecture.html"/>
+    <menu name="Hands-On">
       <item name="Quick Start" href="./Quickstart.html"/>
       <item name="Tutorial" href="./Tutorial.html"/>
+      <item name="Javadocs" href="http://helix.incubator.apache.org/apidocs"/>
     </menu>
 
     <menu name="Recipes">
@@ -102,9 +103,29 @@
   </body>
 
   <custom>
-    <fluidoSkin>
+    <reflowSkin>
+      <theme>bootswatch-cerulean</theme>
+      <highlightJs>false</highlightJs>
+      <brand>
+        <name>Apache Helix</name>
+        <href>http://helix.incubator.apache.org</href>
+      </brand>
+      <slogan>A cluster management framework for partitioned and replicated distributed
resources</slogan>
+      <bottomNav>
+        <column>Get Helix</column>
+        <column>Hands-On</column>
+        <column>Recipes</column>
+      </bottomNav>
+      <pages>
+        <index>
+          <sections>
+            <columns>3</columns>
+          </sections>
+        </index>
+      </pages>
+    </reflowSkin>
+    <!--fluidoSkin>
       <topBarEnabled>true</topBarEnabled>
-      <!-- twitter link work only with sidebar disabled -->
       <sideBarEnabled>true</sideBarEnabled>
       <googleSearch></googleSearch>
       <twitter>
@@ -112,7 +133,7 @@
         <showUser>true</showUser>
         <showFollowers>false</showFollowers>
       </twitter>
-    </fluidoSkin>
+    </fluidoSkin-->
   </custom>
 
 </project>

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/4a4510d1/site-releases/trunk/src/site/xdoc/download.xml.vm
----------------------------------------------------------------------
diff --git a/site-releases/trunk/src/site/xdoc/download.xml.vm b/site-releases/trunk/src/site/xdoc/download.xml.vm
index 41355db..2a4d76e 100644
--- a/site-releases/trunk/src/site/xdoc/download.xml.vm
+++ b/site-releases/trunk/src/site/xdoc/download.xml.vm
@@ -18,13 +18,13 @@ specific language governing permissions and limitations
 under the License.
 
 -->
-#set( $releaseName = "0.7.0-incubating" )
-#set( $releaseDate = "10/31/2013" )
+#set( $releaseName = "0.7.1" )
+#set( $releaseDate = "TBA" )
 <document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
 
   <properties>
-    <title>Apache Incubator Helix Downloads</title>
+    <title>Apache Helix Downloads</title>
     <author email="dev@helix.incubator.apache.org">Apache Helix Documentation Team</author>
   </properties>
 
@@ -34,11 +34,11 @@ under the License.
         <param name="class" value="toc"/>
       </macro>
     </div>
-    
+
     <section name="Introduction">
       <p>Apache Helix artifacts are distributed in source and binary form under the
terms of the
         <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version
2.0</a>.
-        See the included <tt>LICENSE</tt> and <tt>NOTICE</tt> files
included in each artifact for additional license 
+        See the included <tt>LICENSE</tt> and <tt>NOTICE</tt> files
included in each artifact for additional license
         information.
       </p>
       <p>Use the links below to download a source distribution of Apache Helix.
@@ -157,22 +157,22 @@ under the License.
 
     <section name="Verifying Releases">
       <p>We strongly recommend you verify the integrity of the downloaded files with
both PGP and MD5.</p>
-      
-      <p>The PGP signatures can be verified using <a href="http://www.pgpi.org/">PGP</a>
or 
-      <a href="http://www.gnupg.org/">GPG</a>. 
+
+      <p>The PGP signatures can be verified using <a href="http://www.pgpi.org/">PGP</a>
or
+      <a href="http://www.gnupg.org/">GPG</a>.
       First download the <a href="http://www.apache.org/dist/incubator/helix/KEYS">KEYS</a>
as well as the
-      <tt>*.asc</tt> signature file for the particular distribution. Make sure
you get these files from the main 
+      <tt>*.asc</tt> signature file for the particular distribution. Make sure
you get these files from the main
       distribution directory, rather than from a mirror. Then verify the signatures using
one of the following sets of
       commands:
 
         <source>$ pgp -ka KEYS
 $ pgp helix-*.zip.asc</source>
-      
+
         <source>$ gpg --import KEYS
 $ gpg --verify helix-*.zip.asc</source>
        </p>
-    <p>Alternatively, you can verify the MD5 signature on the files. A Unix/Linux program
called  
-      <code>md5</code> or 
+    <p>Alternatively, you can verify the MD5 signature on the files. A Unix/Linux program
called
+      <code>md5</code> or
       <code>md5sum</code> is included in most distributions.  It is also available
as part of
       <a href="http://www.gnu.org/software/textutils/textutils.html">GNU Textutils</a>.
       Windows users can get binary md5 programs from these (and likely other) places:

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/4a4510d1/src/site/markdown/index.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index 6d5154e..3895098 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -73,7 +73,7 @@ Apache Helix has two new releases:
 
     [\[Quick Start\]](./site-releases/0.6.2-incubating-site/Quickstart.html) [\[Release Notes\]](./releasenotes/release-0.6.2-incubating.html)
 
-* [0.7.0-incubating](./site-releases/0.7.0-incubating-site/index.html) - A release that includes
high-level APIs to logically interact with Participants, Controllers, Resources, and other
Helix constructs. __This release is an alpha and APIs are in the process of being finalized__.
Feel free to play with it and provide any feedback you have!
+* [0.7.0-incubating](./site-releases/0.7.0-incubating-site/index.html) (alpha) - A release
that includes high-level APIs to logically interact with Participants, Controllers, Resources,
and other Helix constructs. __This release is an alpha and APIs are in the process of being
finalized__. Feel free to play with it and provide any feedback you have!
 
     [\[Quick Start\]](./site-releases/0.7.0-incubating-site/Quickstart.html) [\[Release Notes\]](./releasenotes/release-0.7.0-incubating.html)
 


Mime
View raw message