Skip to content

Commit

Permalink
Rename ChildrenRequestPolicy to the more accurate ChildrenRetrievalPo…
Browse files Browse the repository at this point in the history 
…licy

References #21
  • Loading branch information
@andreashuber-lawo
andreashuber-lawo committed Apr 22, 2016
1 parent d0e364d commit 7849a6f
Show file tree
Hide file tree
Showing 8 changed files with 70 additions and 69 deletions.
24 changes: 12 additions & 12 deletions Lawo.EmberPlusSharp/Model/ChildrenRequestPolicy.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,25 +6,25 @@

namespace Lawo.EmberPlusSharp.Model
{
/// <summary>Represents the policy how children for a given node should be requested from the provider.</summary>
public enum ChildrenRequestPolicy
/// <summary>Represents the policy how children for a given node should be retrieved from the provider.</summary>
public enum ChildrenRetrievalPolicy
{
/// <summary>Do not request any children.</summary>
/// <remarks>No children will be requested as long as the <see cref="INode.ChildrenRequestPolicy"/>
/// <summary>Do not retrieve any children.</summary>
/// <remarks>No children will be retrieved as long as the <see cref="INode.ChildrenRetrievalPolicy"/>
/// property of an <see cref="INode"/> implementation has this value.</remarks>
None,

/// <summary>Request only direct children.</summary>
/// <remarks>If the <see cref="INode.ChildrenRequestPolicy"/> property of an <see cref="INode"/> implementation
/// has this value then only direct children were or will be requested for the node. The
/// <see cref="INode.ChildrenRequestPolicy"/> property of the direct children implementing <see cref="INode"/>
/// <summary>Retrieve only direct children.</summary>
/// <remarks>If the <see cref="INode.ChildrenRetrievalPolicy"/> property of an <see cref="INode"/> implementation
/// has this value then only direct children were or will be retrieved for the node. The
/// <see cref="INode.ChildrenRetrievalPolicy"/> property of the direct children implementing <see cref="INode"/>
/// will have the initial value <see cref="None"/>.</remarks>
DirectOnly,

/// <summary>Request direct and indirect children.</summary>
/// <remarks>If the <see cref="INode.ChildrenRequestPolicy"/> property of an <see cref="INode"/> implementation
/// has this value, then all direct and indirect children were or will be requested for the node. The
/// <see cref="INode.ChildrenRequestPolicy"/> property of the direct and indirect children implementing
/// <summary>Retrieve direct and indirect children.</summary>
/// <remarks>If the <see cref="INode.ChildrenRetrievalPolicy"/> property of an <see cref="INode"/> implementation
/// has this value, then all direct and indirect children were or will be retrieved for the node. The
/// <see cref="INode.ChildrenRetrievalPolicy"/> property of the direct and indirect children implementing
/// <see cref="INode"/> will have the value <see cref="All"/>.</remarks>
All
}
Expand Down
39 changes: 20 additions & 19 deletions Lawo.EmberPlusSharp/Model/Consumer.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -86,14 +86,14 @@ public Task SendChangesAsync()
/// <exception cref="Exception">An exception was thrown from one of the callbacks passed to the
/// <see cref="S101Client"/> constructor, see <see cref="Exception.Message"/> for more information.</exception>
/// <exception cref="InvalidOperationException">This method was called from a thread other than the one that
/// executed <see cref="CreateAsync(S101Client, int, ChildrenRequestPolicy, byte)"/>.</exception>
/// executed <see cref="CreateAsync(S101Client, int, ChildrenRetrievalPolicy, byte)"/>.</exception>
/// <exception cref="ObjectDisposedException"><see cref="Dispose"/> has been called or the connection has been
/// lost.</exception>
/// <exception cref="OperationCanceledException"><see cref="Dispose"/> has been called or the connection has
/// been lost.</exception>
/// <remarks>Also retrieves the children of any objects implementing <see cref="INode"/> that have had their
/// <see cref="INode.ChildrenRequestPolicy"/> property set to a value other than
/// <see cref="ChildrenRequestPolicy.None"/>.</remarks>
/// <see cref="INode.ChildrenRetrievalPolicy"/> property set to a value other than
/// <see cref="ChildrenRetrievalPolicy.None"/>.</remarks>
public async Task SendAsync()
{
if (this.root.HasChanges)
Expand Down Expand Up @@ -143,32 +143,33 @@ public static Task<Consumer<TRoot>> CreateAsync(S101Client client, int timeout)
return CreateAsync(client, timeout, (byte)0x00);
}

/// <summary>Returns the return value of <see cref="CreateAsync(S101Client, int, ChildrenRequestPolicy, byte)">
/// CreateAsync(<paramref name="client"/>, <paramref name="timeout"/>, <paramref name="childrenRequestPolicy"/>,
/// <summary>Returns the return value of <see cref="CreateAsync(S101Client, int, ChildrenRetrievalPolicy, byte)">
/// CreateAsync(<paramref name="client"/>, <paramref name="timeout"/>, <paramref name="childrenRetrievalPolicy"/>,
/// 0x00)</see>.
/// </summary>
[SuppressMessage("Microsoft.Design", "CA1000:DoNotDeclareStaticMembersOnGenericTypes", Justification = "There's no other way.")]
public static Task<Consumer<TRoot>> CreateAsync(S101Client client, int timeout, ChildrenRequestPolicy childrenRequestPolicy)
public static Task<Consumer<TRoot>> CreateAsync(
S101Client client, int timeout, ChildrenRetrievalPolicy childrenRetrievalPolicy)
{
return CreateAsync(client, timeout, childrenRequestPolicy, 0x00);
return CreateAsync(client, timeout, childrenRetrievalPolicy, 0x00);
}

/// <summary>Returns the return value of <see cref="CreateAsync(S101Client, int, ChildrenRequestPolicy, byte)">
/// <summary>Returns the return value of <see cref="CreateAsync(S101Client, int, ChildrenRetrievalPolicy, byte)">
/// CreateAsync(<paramref name="client"/>, <paramref name="timeout"/>,
/// <see cref="ChildrenRequestPolicy.All">ChildrenRequestPolicy.All</see>, <paramref name="slot"/>)</see>.
/// <see cref="ChildrenRetrievalPolicy.All">ChildrenRetrievalPolicy.All</see>, <paramref name="slot"/>)</see>.
/// </summary>
[SuppressMessage("Microsoft.Design", "CA1000:DoNotDeclareStaticMembersOnGenericTypes", Justification = "There's no other way.")]
public static Task<Consumer<TRoot>> CreateAsync(S101Client client, int timeout, byte slot)
{
return CreateAsync(client, timeout, ChildrenRequestPolicy.All, slot);
return CreateAsync(client, timeout, ChildrenRetrievalPolicy.All, slot);
}

/// <summary>Asynchronously uses <paramref name="client"/> to create a new <see cref="Consumer{T}"/> object.
/// </summary>
/// <param name="client">The <see cref="S101Client"/> to use.</param>
/// <param name="timeout">The total amount of time, in milliseconds, this method will wait for the provider to
/// send all requested elements. Specify -1 to wait indefinitely.</param>
/// <param name="childrenRequestPolicy">The policy that defines whether direct and indirect children are
/// <param name="childrenRetrievalPolicy">The policy that defines whether direct and indirect children are
/// retrieved from the provider before this method returns.</param>
/// <param name="slot">The slot to communicate with. All outgoing <see cref="S101Message"/> objects will have
/// their <see cref="S101Message.Slot"/> property set to this value. Incoming messages are ignored, if their
Expand All @@ -185,11 +186,11 @@ public static Task<Consumer<TRoot>> CreateAsync(S101Client client, int timeout,
/// <exception cref="TimeoutException">The provider did not send all requested elements within the specified
/// <paramref name="timeout"/>.</exception>
/// <remarks>
/// <para>Sets the <see cref="INode.ChildrenRequestPolicy"/> property of the <see cref="Root"/> object to the
/// value passed for <paramref name="childrenRequestPolicy"/> and then retrieves a partial or full copy of the
/// <para>Sets the <see cref="INode.ChildrenRetrievalPolicy"/> property of the <see cref="Root"/> object to the
/// value passed for <paramref name="childrenRetrievalPolicy"/> and then retrieves a partial or full copy of the
/// provider tree before returning the <see cref="Consumer{TRoot}"/> object. Exactly what elements are initially
/// requested from the provider depends on the type of <typeparamref name="TRoot"/> and the value of
/// <paramref name="childrenRequestPolicy"/>.</para>
/// retrieved from the provider depends on the type of <typeparamref name="TRoot"/> and the value of
/// <paramref name="childrenRetrievalPolicy"/>.</para>
/// <para>Afterwards, all changes are continuously synchronized such that the state of the object tree
/// accessible through the <see cref="Root"/> property mirrors the state of the tree held by the provider.
/// </para>
Expand All @@ -198,9 +199,9 @@ public static Task<Consumer<TRoot>> CreateAsync(S101Client client, int timeout,
/// </remarks>
[SuppressMessage("Microsoft.Design", "CA1000:DoNotDeclareStaticMembersOnGenericTypes", Justification = "There's no other way.")]
public static async Task<Consumer<TRoot>> CreateAsync(
S101Client client, int timeout, ChildrenRequestPolicy childrenRequestPolicy, byte slot)
S101Client client, int timeout, ChildrenRetrievalPolicy childrenRetrievalPolicy, byte slot)
{
var result = new Consumer<TRoot>(client, timeout, childrenRequestPolicy, slot);
var result = new Consumer<TRoot>(client, timeout, childrenRetrievalPolicy, slot);
await result.RetrieveChildrenAsync();
result.ReceiveLoop();
result.AutoSendLoop();
Expand All @@ -223,9 +224,9 @@ public static async Task<Consumer<TRoot>> CreateAsync(

////////////////////////////////////////////////////////////////////////////////////////////////////////////////

private Consumer(S101Client client, int timeout, ChildrenRequestPolicy childrenRequestPolicy, byte slot)
private Consumer(S101Client client, int timeout, ChildrenRetrievalPolicy childrenRetrievalPolicy, byte slot)
{
this.root = Root<TRoot>.Construct(new Context(null, 0, string.Empty, childrenRequestPolicy));
this.root = Root<TRoot>.Construct(new Context(null, 0, string.Empty, childrenRetrievalPolicy));
this.client = client;
this.childrenRetrievalTimeout = timeout;
this.emberDataMessage = new S101Message(slot, EmberDataCommand);
Expand Down
8 changes: 4 additions & 4 deletions Lawo.EmberPlusSharp/Model/Context.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,16 +9,16 @@ namespace Lawo.EmberPlusSharp.Model
internal sealed class Context
{
internal Context(IParent parent, int number, string identifier) :
this(parent, number, identifier, ChildrenRequestPolicy.All)
this(parent, number, identifier, ChildrenRetrievalPolicy.All)
{
}

internal Context(IParent parent, int number, string identifier, ChildrenRequestPolicy childrenRequestPolicy)
internal Context(IParent parent, int number, string identifier, ChildrenRetrievalPolicy childrenRetrievalPolicy)
{
this.Parent = parent;
this.Number = number;
this.Identifier = identifier;
this.ChildrenRequestPolicy = childrenRequestPolicy;
this.ChildrenRetrievalPolicy = childrenRetrievalPolicy;
}

internal IParent Parent { get; }
Expand All @@ -27,6 +27,6 @@ internal Context(IParent parent, int number, string identifier, ChildrenRequestP

internal string Identifier { get; }

internal ChildrenRequestPolicy ChildrenRequestPolicy { get; }
internal ChildrenRetrievalPolicy ChildrenRetrievalPolicy { get; }
}
}
8 changes: 4 additions & 4 deletions Lawo.EmberPlusSharp/Model/INode.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,13 +19,13 @@ public interface INode : IElementWithSchemas

/// <summary>Gets or sets the policy for this node.</summary>
/// <exception cref="ArgumentException">Attempted to set a new value when the current value is not equal to
/// <see cref="ChildrenRequestPolicy.None"/>.</exception>
/// <see cref="ChildrenRetrievalPolicy.None"/>.</exception>
/// <exception cref="ArgumentOutOfRangeException">Attempted to set a value that is not equal to one of the named
/// constants of <see cref="ChildrenRequestPolicy"/>.</exception>
/// <remarks>Setting this property prompts the consumer to automatically request children according to the new
/// constants of <see cref="ChildrenRetrievalPolicy"/>.</exception>
/// <remarks>Setting this property prompts the consumer to automatically retrieve children according to the new
/// value. To wait for the children to be retrieved, <see langword="await"/> the result of a call to
/// <see cref="Consumer{TRoot}.SendAsync"/>.</remarks>
ChildrenRequestPolicy ChildrenRequestPolicy { get; set; }
ChildrenRetrievalPolicy ChildrenRetrievalPolicy { get; set; }

/// <summary>Gets the children of this node.</summary>
ReadOnlyObservableCollection<IElement> Children { get; }
Expand Down
22 changes: 11 additions & 11 deletions Lawo.EmberPlusSharp/Model/NodeBase.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,35 +25,35 @@ public abstract class NodeBase<TMostDerived> : ElementWithSchemas<TMostDerived>,
where TMostDerived : NodeBase<TMostDerived>
{
private readonly SortedDictionary<int, Element> children = new SortedDictionary<int, Element>();
private ChildrenRequestPolicy childrenRequestPolicy;
private ChildrenRetrievalPolicy childrenRetrievalPolicy;

////////////////////////////////////////////////////////////////////////////////////////////////////////////////

/// <inheritdoc/>
public ChildrenRequestPolicy ChildrenRequestPolicy
public ChildrenRetrievalPolicy ChildrenRetrievalPolicy
{
get
{
return this.childrenRequestPolicy;
return this.childrenRetrievalPolicy;
}

set
{
if ((value < ChildrenRequestPolicy.None) || (value > ChildrenRequestPolicy.All))
if ((value < ChildrenRetrievalPolicy.None) || (value > ChildrenRetrievalPolicy.All))
{
throw new ArgumentOutOfRangeException("value");
}

if (value != this.childrenRequestPolicy)
if (value != this.childrenRetrievalPolicy)
{
if (this.childrenRequestPolicy != ChildrenRequestPolicy.None)
if (this.childrenRetrievalPolicy != ChildrenRetrievalPolicy.None)
{
throw new ArgumentException(
"A new value cannot be set if the current value is not equal to ChildrenRequestPolicy.None.",
"A new value cannot be set if the current value is not equal to ChildrenRetrievalPolicy.None.",
"value");
}

this.SetValue(ref this.childrenRequestPolicy, value);
this.SetValue(ref this.childrenRetrievalPolicy, value);
}
}
}
Expand Down Expand Up @@ -87,7 +87,7 @@ internal NodeBase() : base(RequestState.None)
internal sealed override void SetContext(Context context)
{
base.SetContext(context);
this.childrenRequestPolicy = context.ChildrenRequestPolicy;
this.childrenRetrievalPolicy = context.ChildrenRetrievalPolicy;
}

internal IElement GetChild(int number)
Expand Down Expand Up @@ -376,8 +376,8 @@ private void ReadChildContents(
{
contentsReader.Read(); // Read what we have written with WriteStartSet above

var newPolicy = this.childrenRequestPolicy == ChildrenRequestPolicy.All ?
ChildrenRequestPolicy.All : ChildrenRequestPolicy.None;
var newPolicy = this.childrenRetrievalPolicy == ChildrenRetrievalPolicy.All ?
ChildrenRetrievalPolicy.All : ChildrenRetrievalPolicy.None;
var context = new Context(this, number, identifier, newPolicy);
child = this.ReadNewChildContents(contentsReader, actualType, context, out childRequestState);

Expand Down
2 changes: 1 addition & 1 deletion Lawo.EmberPlusSharpTest/Lawo.EmberPlusSharpTest.csproj
View file
Original file line number Diff line number Diff line change
Expand Up @@ -581,7 +581,7 @@
<EmbeddedResource Include="Model\Test\EmberDataPayloads\StreamLog.xml" />
</ItemGroup>
<ItemGroup>
<EmbeddedResource Include="Model\Test\EmberDataPayloads\ChildrenRequestStateLog.xml">
<EmbeddedResource Include="Model\Test\EmberDataPayloads\ChildrenRetrievalPolicyLog.xml">
<SubType>Designer</SubType>
</EmbeddedResource>
</ItemGroup>
Expand Down
Loading

0 comments on commit 7849a6f

Please sign in to comment.