second revision

lang/cs/Org.Apache.REEF.IO/BlockManagement/Block/BlockFactory.cs

@@ -0,0 +1,14 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+using Org.Apache.REEF.Common.Attributes;
+
+namespace Org.Apache.REEF.IO.BlockManagement.Block
+{
+    [Unstable("0.14", "New feature. Interface can change substantially.")]
+    internal sealed class BlockFactory
+    {
+    }
+}

lang/cs/Org.Apache.REEF.IO/BlockManagement/Block/IBlock.cs

@@ -15,6 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
+using System.Collections.Generic;
 using System.IO;
 using Org.Apache.REEF.Common.Attributes;
 using Org.Apache.REEF.IO.BlockManagement.Partition;
@@ -26,10 +27,12 @@ namespace Org.Apache.REEF.IO.BlockManagement.Block
     /// The atomic unit of the Block Management framework in REEF.
     /// </summary>
     [Unstable("0.14", "New feature. Interface can change substantially.")]
-    public interface IBlock : IIdentifiable
+    internal interface IBlock : IUniquelyIdentifiable
     {
         /// <summary>
         /// The partition that the block belongs to.
+        /// Can potentially make a remote connection if the block was retrieved only 
+        /// with the Uid.
         /// </summary>
         IPartition Partition { get; }
 
@@ -39,22 +42,13 @@ public interface IBlock : IIdentifiable
         Location Location { get; }
 
         /// <summary>
-        /// Opens the block.
+        /// Whether the block can be written to.
         /// </summary>
-        Stream DataStream { get; }
+        bool CanWrite { get; }
 
         /// <summary>
-        /// Localizes a block and caches in memory if not already localized.
-        /// The BlockManager will register the newly localized block
-        /// with the BlockManagerMaster.
+        /// Localizes and "opens" the block.
         /// </summary>
-        void LocalizeBlockInMemory();
-
-        /// <summary>
-        /// Localizes a block and puts onto disk if not already on disk.
-        /// The BlockManager will register the newly localized block with
-        /// the BlockManagerMaster.
-        /// </summary>
-        void LocalizeBlockOnDisk(string filePath);
+        IList<byte> Data { get; set; }
     }
 }

lang/cs/Org.Apache.REEF.IO/BlockManagement/Block/ReadonlyBlock.cs

@@ -0,0 +1,62 @@
+// 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.
+
+using System;
+using System.Collections.Generic;
+using Org.Apache.REEF.Common.Attributes;
+using Org.Apache.REEF.IO.BlockManagement.Partition;
+
+namespace Org.Apache.REEF.IO.BlockManagement.Block
+{
+    /// <summary>
+    /// A readonly implementation of <see cref="IBlock"/>.
+    /// </summary>
+    [Unstable("0.14", "New feature. Implementation can change substantially.")]
+    public sealed class ReadonlyBlock : IBlock
+    {
+        public Guid Uid { get; private set; }
+
+        public IPartition Partition { get; private set; }
+
+        public Location Location { get; private set; }
+
+        public bool CanWrite
+        {
+            get
+            {
+                return false;
+            }
+        }
+
+        public IList<byte> Data
+        {
+            get
+            {
+                // TODO: Lazily fetch data into memory for consumption.
+                // TODO: Register with BlockManager that there is local copy.
+                // TODO: Return IReadOnlyList.
+                Location = Location.InMemory;
+                throw new NotImplementedException();
+            }
+
+            set
+            {
+                throw new NotSupportedException("Readable blocks are not set-able.");
+            }
+        }
+    }
+}

lang/cs/Org.Apache.REEF.IO/BlockManagement/Block/WritableBlock.cs

@@ -0,0 +1,68 @@
+// 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.
+
+using System;
+using System.Collections.Generic;
+using Org.Apache.REEF.Common.Attributes;
+using Org.Apache.REEF.IO.BlockManagement.Partition;
+
+namespace Org.Apache.REEF.IO.BlockManagement.Block
+{
+    /// <summary>
+    /// A block that can be written to.
+    /// </summary>
+    [Unstable("0.14", "New feature. Implementation can change substantially.")]
+    public sealed class WritableBlock : IBlock
+    {
+        internal WritableBlock(IPartition partition, Guid uid)
+        {
+            Partition = partition;
+            Uid = uid;
+            CanWrite = true;
+            Data = new List<byte>();
+        }
+
+        public Guid Uid { get; private set; }
+
+        public IPartition Partition { get; private set; }
+
+        public Location Location
+        {
+            get
+            {
+                return Location.InMemory;
+            }
+        }
+
+        public bool CanWrite { get; private set; }
+
+        /// <summary>
+        /// Data can only be mutated before commit.
+        /// </summary>
+        public IList<byte> Data { get; set; }
+
+        /// <summary>
+        /// Commits the block with the BlockManager and disables write on the WritableBlock.
+        /// </summary>
+        public ReadonlyBlock Commit()
+        {
+            // TODO: Commit the block with the BlockManager and return a ReadonlyBlock if success.
+            CanWrite = false;
+            throw new NotImplementedException();
+        }
+    }
+}

lang/cs/Org.Apache.REEF.IO/BlockManagement/BlockManager.cs

@@ -26,6 +26,9 @@
 
 namespace Org.Apache.REEF.IO.BlockManagement
 {
+    /// <summary>
+    /// The local BlockManager that enables operations on datasets, blocks, and partitions.
+    /// </summary>
     [Unstable("0.14", "New feature. Implementation can change substantially.")]
     public sealed class BlockManager
     {
@@ -60,6 +63,14 @@ public IDataSet GetDataSet(string dataSetId)
             throw new NotImplementedException();
         }
 
+        /// <summary>
+        /// Gets a readonly block with its universal identifier.
+        /// </summary>
+        public ReadonlyBlock GetBlock(Guid blockUid)
+        {
+            throw new NotImplementedException();
+        }
+
         /// <summary>
         /// Called by <see cref="IDataSet.GetPartition"/> to return a
         /// Partition of the DataSet. Does not make remote requests. The Partition
@@ -84,35 +95,17 @@ internal IEnumerable<IPartition> FetchPartitions(IDataSet dataSet)
         /// Called by <see cref="IPartition.FetchBlocks"/> to internally fetch
         /// blocks from the BlockManagerMaster.
         /// </summary>
-        internal IEnumerable<IBlock> FetchBlocks(IPartition partition)
-        {
-            throw new NotImplementedException();
-        }
-
-        /// <summary>
-        /// Called by <see cref="IBlock.LocalizeBlockInMemory"/>. Contacts the
-        /// BlockManagerMaster if Block is not already local to learn where the
-        /// Block is. Saves the block in memory.
-        /// If the Block is on another BlockManager, the BlockManager will contact
-        /// the other BlockManager to fetch the data.
-        /// If the Block is on an external source, the BlockManager will fetch the Block
-        /// based on its description.
-        /// </summary>
-        internal void LocalizeBlockInMemory()
+        internal IEnumerable<ReadonlyBlock> FetchBlocks(IPartition partition)
         {
             throw new NotImplementedException();
         }
 
         /// <summary>
-        /// Called by <see cref="IBlock.LocalizeBlockOnDisk"/>. Contacts the
-        /// BlockManagerMaster if Block is not already local to learn where the
-        /// Block is. Saves the block on disk.
-        /// If the Block is on another BlockManager, the BlockManager will contact
-        /// the other BlockManager to fetch the data.
-        /// If the Block is on an external source, the BlockManager will fetch the Block
-        /// based on its description.
+        /// Called by <see cref="WritableBlock.Commit"/> to internally
+        /// commit a block with the BlockManagerMaster.
         /// </summary>
-        internal void LocalizeBlockOnDisk(string filePath)
+        /// TODO: Consider supporting batching commits.
+        internal ReadonlyBlock CommitBlock(WritableBlock writableBlock)
         {
             throw new NotImplementedException();
         }

lang/cs/Org.Apache.REEF.IO/BlockManagement/Partition/IPartition.cs

@@ -15,6 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
+using System;
 using System.Collections.Generic;
 using Org.Apache.REEF.Common.Attributes;
 using Org.Apache.REEF.IO.BlockManagement.Block;
@@ -36,7 +37,7 @@ public interface IPartition : IIdentifiable
         /// Gets a block within the partition. Does not make
         /// any remote connections.
         /// </summary>
-        IBlock GetBlock(string blockId);
+        ReadonlyBlock GetBlock(Guid blockUid);
 
         /// <summary>
         /// The DataSet that the Partition is a part of.
@@ -46,6 +47,6 @@ public interface IPartition : IIdentifiable
         /// <summary>
         /// Fetches the Blocks of a partition remotely from the BlockManagerMaster.
         /// </summary>
-        IEnumerable<IBlock> FetchBlocks();
+        IEnumerable<ReadonlyBlock> FetchBlocks();
     }
 }

lang/cs/Org.Apache.REEF.IO/BlockManagement/Partition/InputPartition.cs

@@ -36,14 +36,14 @@ private InputPartition()
 
         public string Id { get; private set; }
 
-        public IBlock GetBlock(string blockId)
+        public IDataSet DataSet { get; private set; }
+
+        public ReadonlyBlock GetBlock(Guid blockUid)
         {
             throw new NotImplementedException();
         }
 
-        public IDataSet DataSet { get; private set; }
-
-        public IEnumerable<IBlock> FetchBlocks()
+        public IEnumerable<ReadonlyBlock> FetchBlocks()
         {
             throw new NotImplementedException();
         }

lang/cs/Org.Apache.REEF.IO/BlockManagement/Partition/OutputPartition.cs

@@ -36,24 +36,23 @@ private OutputPartition()
 
         public string Id { get; private set; }
 
-        public IBlock GetBlock(string blockId)
+        public ReadonlyBlock GetBlock(Guid blockUid)
         {
             throw new NotImplementedException();
         }
 
         public IDataSet DataSet { get; private set; }
 
-        public IEnumerable<IBlock> FetchBlocks()
+        public IEnumerable<ReadonlyBlock> FetchBlocks()
         {
             throw new NotImplementedException();
         }
 
         /// <summary>
-        /// Appends a block to the OutputPartition.
-        /// Assigns the BlockID to the Block. Fails if the
-        /// <see cref="IBlock"/> already has an assinged BlockID.
+        /// Allocates a <see cref="WritableBlock"/>, which allows the user to
+        /// commit blocks into the block management framework.
         /// </summary>
-        public void AppendBlock(IBlock block)
+        public WritableBlock AllocateBlock()
         {
             throw new NotImplementedException();
         }

lang/cs/Org.Apache.REEF.IO/Org.Apache.REEF.IO.csproj

@@ -70,6 +70,9 @@ under the License.
   </ItemGroup>
   <ItemGroup>
     <Compile Include="BlockManagement\BlockManager.cs" />
+    <Compile Include="BlockManagement\Block\BlockFactory.cs" />
+    <Compile Include="BlockManagement\Block\WritableBlock.cs" />
+    <Compile Include="BlockManagement\Block\ReadableBlock.cs" />
     <Compile Include="BlockManagement\Block\Location.cs" />
     <Compile Include="BlockManagement\Block\IBlock.cs" />
     <Compile Include="BlockManagement\DataSet\IDataSet.cs" />

lang/cs/Org.Apache.REEF.Utilities/IUniquelyIdentifiable.cs

@@ -0,0 +1,32 @@
+// 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.
+
+using System;
+
+namespace Org.Apache.REEF.Utilities
+{
+    /// <summary>
+    /// Denotes an object that is globally, uniquely identifiable.
+    /// </summary>
+    public interface IUniquelyIdentifiable
+    {
+        /// <summary>
+        /// The unique ID of the object.
+        /// </summary>
+        Guid Uid { get; }
+    }
+}

lang/cs/Org.Apache.REEF.Utilities/Org.Apache.Reef.Utilities.csproj

@@ -44,6 +44,7 @@ under the License.
     <Compile Include="Diagnostics\Exceptions.cs" />
     <Compile Include="IIdentifiable.cs" />
     <Compile Include="IMessage.cs" />
+    <Compile Include="IUniquelyIdentifiable.cs" />
     <Compile Include="Logging\JavaLoggingSetting.cs" />
     <Compile Include="Logging\Level.cs" />
     <Compile Include="Logging\Logger.cs" />