Skip to content

Commit

Permalink
[api-docs] More documentation
Browse files Browse the repository at this point in the history 
This PR fleshes out more of the documentation labeled as TBD.
  • Loading branch information
@sean-gilliam
sean-gilliam committed Mar 31, 2017
1 parent 6f9463e commit d4ba4ec
Show file tree
Hide file tree
Showing 38 changed files with 1,059 additions and 648 deletions.
17 changes: 9 additions & 8 deletions src/contrib/cluster/Akka.Cluster.Sharding/PersistentShardCoordinator.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -90,22 +90,23 @@ public State Updated(IDomainEvent e)
if (e is ShardRegionRegistered)
{
var message = e as ShardRegionRegistered;
if (Regions.ContainsKey(message.Region)) throw new ArgumentException(string.Format("Region {0} is already registered", message.Region));
if (Regions.ContainsKey(message.Region)) throw new ArgumentException($"Region {message.Region} is already registered");

return Copy(regions: Regions.SetItem(message.Region, ImmutableList<ShardId>.Empty));
}
else if (e is ShardRegionProxyRegistered)
{
var message = e as ShardRegionProxyRegistered;
if (RegionProxies.Contains(message.RegionProxy)) throw new ArgumentException(string.Format("Region proxy {0} is already registered", message.RegionProxy));
if (RegionProxies.Contains(message.RegionProxy)) throw new ArgumentException($"Region proxy {message.RegionProxy} is already registered");

return Copy(regionProxies: RegionProxies.Add(message.RegionProxy));
}
else if (e is ShardRegionTerminated)
{
IImmutableList<ShardId> shardRegions;
var message = e as ShardRegionTerminated;
if (!Regions.TryGetValue(message.Region, out shardRegions)) throw new ArgumentException(string.Format("Region {0} not registered", message.Region));
if (!Regions.TryGetValue(message.Region, out shardRegions)) throw new ArgumentException(
$"Region {message.Region} not registered");

return Copy(
regions: Regions.Remove(message.Region),
Expand All @@ -115,16 +116,16 @@ public State Updated(IDomainEvent e)
else if (e is ShardRegionProxyTerminated)
{
var message = e as ShardRegionProxyTerminated;
if (!RegionProxies.Contains(message.RegionProxy)) throw new ArgumentException(string.Format("Region proxy {0} not registered", message.RegionProxy));
if (!RegionProxies.Contains(message.RegionProxy)) throw new ArgumentException($"Region proxy {message.RegionProxy} not registered");

return Copy(regionProxies: RegionProxies.Remove(message.RegionProxy));
}
else if (e is ShardHomeAllocated)
{
IImmutableList<ShardId> shardRegions;
var message = e as ShardHomeAllocated;
if (!Regions.TryGetValue(message.Region, out shardRegions)) throw new ArgumentException(string.Format("Region {0} not registered", message.Region));
if (Shards.ContainsKey(message.Shard)) throw new ArgumentException(string.Format("Shard {0} is already allocated", message.Shard));
if (!Regions.TryGetValue(message.Region, out shardRegions)) throw new ArgumentException($"Region {message.Region} not registered");
if (Shards.ContainsKey(message.Shard)) throw new ArgumentException($"Shard {message.Shard} is already allocated");

return Copy(
shards: Shards.SetItem(message.Shard, message.Region),
Expand All @@ -136,8 +137,8 @@ public State Updated(IDomainEvent e)
IActorRef region;
IImmutableList<ShardId> shardRegions;
var message = e as ShardHomeDeallocated;
if (!Shards.TryGetValue(message.Shard, out region)) throw new ArgumentException(string.Format("Shard {0} not allocated", message.Shard));
if (!Regions.TryGetValue(region, out shardRegions)) throw new ArgumentException(string.Format("Region {0} for shard {1} not registered", region, message.Shard));
if (!Shards.TryGetValue(message.Shard, out region)) throw new ArgumentException($"Shard {message.Shard} not allocated");
if (!Regions.TryGetValue(region, out shardRegions)) throw new ArgumentException($"Region {region} for shard {message.Shard} not registered");

return Copy(
shards: Shards.Remove(message.Shard),
Expand Down
58 changes: 31 additions & 27 deletions src/contrib/cluster/Akka.Cluster.Sharding/Serialization/ClusterShardingMessageSerializer.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,9 +65,9 @@ public class ClusterShardingMessageSerializer : SerializerWithStringManifest
private ExtendedActorSystem _system;

/// <summary>
/// TBD
/// Initializes a new instance of the <see cref="ClusterShardingMessageSerializer"/> class.
/// </summary>
/// <param name="system">TBD</param>
/// <param name="system">The actor system to associate with this serializer.</param>
public ClusterShardingMessageSerializer(ExtendedActorSystem system) : base(system)
{
_system = system;
Expand Down Expand Up @@ -106,16 +106,19 @@ public ClusterShardingMessageSerializer(ExtendedActorSystem system) : base(syste
}

/// <summary>
/// TBD
/// Completely unique value to identify this implementation of Serializer, used to optimize network traffic
/// Values from 0 to 16 is reserved for Akka internal usage
/// </summary>
public override int Identifier { get { return _identifier; } }

/// <summary>
/// TBD
/// Serializes the given object into a byte array
/// </summary>
/// <param name="obj">TBD</param>
/// <exception cref="ArgumentException">TBD</exception>
/// <returns>TBD</returns>
/// <param name="obj">The object to serialize</param>
/// <exception cref="ArgumentException">
/// This exception is thrown when the specified <paramref name="obj"/> is of an unknown type.
/// </exception>
/// <returns>A byte array containing the serialized object</returns>
public override byte[] ToBinary(object obj)
{
if (obj is PersistentShardCoordinator.State) return Compress(CoordinatorStateToProto((PersistentShardCoordinator.State)obj));
Expand Down Expand Up @@ -143,33 +146,40 @@ public override byte[] ToBinary(object obj)
if (obj is Shard.GetShardStats) return new byte[0];
if (obj is Shard.ShardStats) return ShardStatsToProto((Shard.ShardStats)obj).ToByteArray();

throw new ArgumentException(string.Format("Can't serialize object of type [{0}] in [{1}]", obj.GetType(), this.GetType()));
throw new ArgumentException($"Can't serialize object of type [{obj.GetType()}] in [{this.GetType()}]");
}

/// <summary>
/// TBD
/// Deserializes a byte array into an object using an optional <paramref name="manifest" /> (type hint).
/// </summary>
/// <param name="binary">TBD</param>
/// <param name="manifest">TBD</param>
/// <exception cref="ArgumentException">TBD</exception>
/// <returns>TBD</returns>
public override object FromBinary(byte[] binary, string manifest)
/// <param name="bytes">The array containing the serialized object</param>
/// <param name="manifest">The type hint used to deserialize the object contained in the array.</param>
/// <exception cref="ArgumentException">
/// This exception is thrown when the specified <paramref name="bytes"/>cannot be deserialized using the specified <paramref name="manifest"/>.
/// </exception>
/// <returns>The object contained in the array</returns>
public override object FromBinary(byte[] bytes, string manifest)
{
Func<byte[], object> factory;
if (_fromBinaryMap.TryGetValue(manifest, out factory))
{
return factory(binary);
return factory(bytes);
}

throw new ArgumentException(string.Format("Unimplemented deserialization of message with manifest [{0}] in [{1}]", manifest, this.GetType()));
throw new ArgumentException($"Unimplemented deserialization of message with manifest [{manifest}] in [{this.GetType()}]");
}

/// <summary>
/// TBD
/// Returns the manifest (type hint) that will be provided in the <see cref="FromBinary(System.Byte[],System.String)" /> method.
/// <note>
/// This method returns <see cref="String.Empty" /> if a manifest is not needed.
/// </note>
/// </summary>
/// <param name="o">TBD</param>
/// <exception cref="ArgumentException">TBD</exception>
/// <returns>TBD</returns>
/// <param name="o">The object for which the manifest is needed.</param>
/// <exception cref="ArgumentException">
/// This exception is thrown when the specified <paramref name="o"/> does not have an associated manifest.
/// </exception>
/// <returns>The manifest needed for the deserialization of the specified <paramref name="o" />.</returns>
public override string Manifest(object o)
{
if (o is Shard.ShardState) return EntityStateManifest;
Expand Down Expand Up @@ -197,7 +207,7 @@ public override string Manifest(object o)
if (o is Shard.GetShardStats) return GetShardStatsManifest;
if (o is Shard.ShardStats) return ShardStatsManifest;

throw new ArgumentException(string.Format("Can't serialize object of type [{0}] in [{1}]", o.GetType(), this.GetType()));
throw new ArgumentException($"Can't serialize object of type [{o.GetType()}] in [{this.GetType()}]");
}

private ShardStats ShardStatsToProto(Shard.ShardStats o)
Expand Down Expand Up @@ -349,9 +359,6 @@ private object CoordinatorStateFromBinary(byte[] binary)
}
}

/// <summary>
/// Compresses the protobuf message using GZIP compression
/// </summary>
private static byte[] Compress(IMessageLite message)
{
using (var bos = new MemoryStream(BufferSize))
Expand All @@ -363,9 +370,6 @@ private static byte[] Compress(IMessageLite message)
}
}

/// <summary>
/// Decompresses the protobuf message using GZIP compression
/// </summary>
private static Stream Decompress(byte[] bytes)
{
return new GZipStream(new MemoryStream(bytes), CompressionMode.Decompress);
Expand Down
54 changes: 31 additions & 23 deletions ...contrib/cluster/Akka.Cluster.Tools/Client/Serialization/ClusterClientMessageSerializer.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@
using System.Collections.Immutable;
using System.IO;
using System.IO.Compression;
using System.Linq;
using Akka.Actor;
using Akka.Serialization;
using Google.ProtocolBuffers;
Expand All @@ -23,9 +22,6 @@ namespace Akka.Cluster.Tools.Client.Serialization
/// </summary>
internal class ClusterClientMessageSerializer : SerializerWithStringManifest
{
/// <summary>
/// TBD
/// </summary>
private const int BufferSize = 1024 * 4;

private const string ContactsManifest = "A";
Expand All @@ -37,14 +33,15 @@ internal class ClusterClientMessageSerializer : SerializerWithStringManifest
private readonly IDictionary<string, Func<byte[], IClusterClientMessage>> _fromBinaryMap;

/// <summary>
/// TBD
/// Completely unique value to identify this implementation of Serializer, used to optimize network traffic
/// Values from 0 to 16 is reserved for Akka internal usage
/// </summary>
public override int Identifier { get; }

/// <summary>
/// TBD
/// Initializes a new instance of the <see cref="ClusterClientMessageSerializer"/> class.
/// </summary>
/// <param name="system">TBD</param>
/// <param name="system">The actor system to associate with this serializer.</param>
public ClusterClientMessageSerializer(ExtendedActorSystem system) : base(system)
{
Identifier = SerializerIdentifierHelper.GetSerializerIdentifierFromConfig(GetType(), system);
Expand All @@ -58,11 +55,15 @@ public ClusterClientMessageSerializer(ExtendedActorSystem system) : base(system)
}

/// <summary>
/// TBD
/// Serializes the given object into a byte array
/// </summary>
/// <param name="obj">TBD</param>
/// <exception cref="ArgumentException">TBD</exception>
/// <returns>TBD</returns>
/// <param name="obj">The object to serialize</param>
/// <exception cref="ArgumentException">
/// This exception is thrown when the specified <paramref name="obj"/> is of an unknown type.
/// Acceptable values include:
/// <see cref="ClusterReceptionist.Contacts"/> | <see cref="ClusterReceptionist.GetContacts"/> | <see cref="ClusterReceptionist.Heartbeat"/> | <see cref="ClusterReceptionist.HeartbeatRsp"/>
/// </exception>
/// <returns>A byte array containing the serialized object</returns>
public override byte[] ToBinary(object obj)
{
if (obj is ClusterReceptionist.Contacts) return Compress(ContactsToProto(obj as ClusterReceptionist.Contacts));
Expand All @@ -74,29 +75,36 @@ public override byte[] ToBinary(object obj)
}

/// <summary>
/// TBD
/// Deserializes a byte array into an object using an optional <paramref name="manifest" /> (type hint).
/// </summary>
/// <param name="bytes">TBD</param>
/// <param name="manifestString">TBD</param>
/// <exception cref="ArgumentException">TBD</exception>
/// <returns>TBD</returns>
public override object FromBinary(byte[] bytes, string manifestString)
/// <param name="bytes">The array containing the serialized object</param>
/// <param name="manifest">The type hint used to deserialize the object contained in the array.</param>
/// <exception cref="ArgumentException">
/// This exception is thrown when the specified <paramref name="bytes"/>cannot be deserialized using the specified <paramref name="manifest"/>.
/// </exception>
/// <returns>The object contained in the array</returns>
public override object FromBinary(byte[] bytes, string manifest)
{
Func<byte[], IClusterClientMessage> deserializer;
if (_fromBinaryMap.TryGetValue(manifestString, out deserializer))
if (_fromBinaryMap.TryGetValue(manifest, out deserializer))
{
return deserializer(bytes);
}

throw new ArgumentException($"Unimplemented deserialization of message with manifest [{manifestString}] in serializer {GetType()}");
throw new ArgumentException($"Unimplemented deserialization of message with manifest [{manifest}] in serializer {GetType()}");
}

/// <summary>
/// TBD
/// Returns the manifest (type hint) that will be provided in the <see cref="FromBinary(System.Byte[],System.String)" /> method.
/// <note>
/// This method returns <see cref="String.Empty" /> if a manifest is not needed.
/// </note>
/// </summary>
/// <param name="o">TBD</param>
/// <exception cref="ArgumentException">TBD</exception>
/// <returns>TBD</returns>
/// <param name="o">The object for which the manifest is needed.</param>
/// <exception cref="ArgumentException">
/// This exception is thrown when the specified <paramref name="o"/> does not have an associated manifest.
/// </exception>
/// <returns>The manifest needed for the deserialization of the specified <paramref name="o" />.</returns>
public override string Manifest(object o)
{
if (o is ClusterReceptionist.Contacts) return ContactsManifest;
Expand Down
Loading

0 comments on commit d4ba4ec

Please sign in to comment.