This is an automated email from the ASF dual-hosted git repository.
blankensteiner pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar-dotpulsar.git
The following commit(s) were added to refs/heads/master by this push:
new b1aa6f9 Adding more documentation
b1aa6f9 is described below
commit b1aa6f92de2fff8af9f234d2516db447f2539915
Author: Daniel Blankensteiner <[email protected]>
AuthorDate: Wed Feb 10 19:29:53 2021 +0100
Adding more documentation
---
src/DotPulsar/ConsumerOptions.cs | 3 +++
src/DotPulsar/ConsumerState.cs | 30 ++++++++++++++++++++++++++++
src/DotPulsar/DotPulsar.csproj | 2 +-
src/DotPulsar/EncryptionPolicy.cs | 18 +++++++++++++++++
src/DotPulsar/ExceptionContext.cs | 15 ++++++++++++++
src/DotPulsar/FaultAction.cs | 14 +++++++++++++
src/DotPulsar/MessageId.cs | 3 +++
src/DotPulsar/MessageMetadata.cs | 3 +++
src/DotPulsar/ProducerOptions.cs | 3 +++
src/DotPulsar/ProducerState.cs | 18 +++++++++++++++++
src/DotPulsar/ReaderOptions.cs | 3 +++
src/DotPulsar/ReaderState.cs | 22 ++++++++++++++++++++
src/DotPulsar/SubscriptionInitialPosition.cs | 10 ++++++++++
src/DotPulsar/SubscriptionType.cs | 18 +++++++++++++++++
14 files changed, 161 insertions(+), 1 deletion(-)
diff --git a/src/DotPulsar/ConsumerOptions.cs b/src/DotPulsar/ConsumerOptions.cs
index 3d12d9f..8496487 100644
--- a/src/DotPulsar/ConsumerOptions.cs
+++ b/src/DotPulsar/ConsumerOptions.cs
@@ -46,6 +46,9 @@ namespace DotPulsar
/// </summary>
public static readonly SubscriptionType DefaultSubscriptionType =
SubscriptionType.Exclusive;
+ /// <summary>
+ /// Initializes a new instance using the specified subscription name
and topic.
+ /// </summary>
public ConsumerOptions(string subscriptionName, string topic)
{
InitialPosition = DefaultInitialPosition;
diff --git a/src/DotPulsar/ConsumerState.cs b/src/DotPulsar/ConsumerState.cs
index e968add..7c77164 100644
--- a/src/DotPulsar/ConsumerState.cs
+++ b/src/DotPulsar/ConsumerState.cs
@@ -14,14 +14,44 @@
namespace DotPulsar
{
+ /// <summary>
+ /// The possible states a consumer can be in.
+ /// </summary>
public enum ConsumerState : byte
{
+ /// <summary>
+ /// The consumer is connected and active. The subscription type is
'Failover' and this consumer is the active consumer.
+ /// </summary>
Active,
+
+ /// <summary>
+ /// The consumer is closed. This is a final state.
+ /// </summary>
Closed,
+
+ /// <summary>
+ /// The consumer is disconnected.
+ /// </summary>
Disconnected,
+
+ /// <summary>
+ /// The consumer is faulted. This is a final state.
+ /// </summary>
Faulted,
+
+ /// <summary>
+ /// The consumer is connected and inactive. The subscription type is
'Failover' and this consumer is not the active consumer.
+ /// </summary>
Inactive,
+
+ /// <summary>
+ /// The consumer has reached the end of the topic. This is a final
state.
+ /// </summary>
ReachedEndOfTopic,
+
+ /// <summary>
+ /// The consumer has unsubscribed. This is a final state.
+ /// </summary>
Unsubscribed
}
}
diff --git a/src/DotPulsar/DotPulsar.csproj b/src/DotPulsar/DotPulsar.csproj
index 1be25e3..0e84b71 100644
--- a/src/DotPulsar/DotPulsar.csproj
+++ b/src/DotPulsar/DotPulsar.csproj
@@ -17,7 +17,7 @@
<PublishRepositoryUrl>true</PublishRepositoryUrl>
<IncludeSymbols>true</IncludeSymbols>
<SymbolPackageFormat>snupkg</SymbolPackageFormat>
- <NoWarn>1591;1701;1702</NoWarn>
+ <NoWarn>1591</NoWarn>
</PropertyGroup>
<ItemGroup>
diff --git a/src/DotPulsar/EncryptionPolicy.cs
b/src/DotPulsar/EncryptionPolicy.cs
index 67a5343..c4d153a 100644
--- a/src/DotPulsar/EncryptionPolicy.cs
+++ b/src/DotPulsar/EncryptionPolicy.cs
@@ -14,11 +14,29 @@
namespace DotPulsar
{
+ /// <summary>
+ /// Encryption policies.
+ /// </summary>
public enum EncryptionPolicy : byte
{
+ /// <summary>
+ /// Never encrypt the connection.
+ /// </summary>
EnforceUnencrypted,
+
+ /// <summary>
+ /// Given the option of encrypting or not, prefer not to.
+ /// </summary>
PreferUnencrypted,
+
+ /// <summary>
+ /// Given the option of encrypting or not, prefer to do so.
+ /// </summary>
PreferEncrypted,
+
+ /// <summary>
+ /// Always encrypt the connection.
+ /// </summary>
EnforceEncrypted
}
}
diff --git a/src/DotPulsar/ExceptionContext.cs
b/src/DotPulsar/ExceptionContext.cs
index c911791..746b654 100644
--- a/src/DotPulsar/ExceptionContext.cs
+++ b/src/DotPulsar/ExceptionContext.cs
@@ -27,9 +27,24 @@ namespace DotPulsar
Result = FaultAction.Rethrow;
}
+ /// <summary>
+ /// The exception caught while executing the operation. This exception
will be thrown if the fault action Result is set to 'ThrowException'.
+ /// </summary>
public Exception Exception { set; get; }
+
+ /// <summary>
+ /// The cancellation token given to the operation.
+ /// </summary>
public CancellationToken CancellationToken { get; }
+
+ /// <summary>
+ /// Gets or sets an indication that the exception has been handled. If
'true' no other exception handlers will be invoked.
+ /// </summary>
public bool ExceptionHandled { get; set; }
+
+ /// <summary>
+ /// Gets or sets the FaultAction.
+ /// </summary>
public FaultAction Result { get; set; }
}
}
diff --git a/src/DotPulsar/FaultAction.cs b/src/DotPulsar/FaultAction.cs
index d03abde..c6475a8 100644
--- a/src/DotPulsar/FaultAction.cs
+++ b/src/DotPulsar/FaultAction.cs
@@ -14,10 +14,24 @@
namespace DotPulsar
{
+ /// <summary>
+ /// Actions to take when an exception has been caught while executing an
operation.
+ /// </summary>
public enum FaultAction : byte
{
+ /// <summary>
+ /// Rethrow the exception.
+ /// </summary>
Rethrow,
+
+ /// <summary>
+ /// Throw the exception from the ExceptionContext.
+ /// </summary>
ThrowException,
+
+ /// <summary>
+ /// Retry the operation.
+ /// </summary>
Retry
}
}
diff --git a/src/DotPulsar/MessageId.cs b/src/DotPulsar/MessageId.cs
index d8d5aef..cdcc2eb 100644
--- a/src/DotPulsar/MessageId.cs
+++ b/src/DotPulsar/MessageId.cs
@@ -41,6 +41,9 @@ namespace DotPulsar
internal MessageId(MessageIdData messageIdData)
=> Data = messageIdData;
+ /// <summary>
+ /// Initializes a new instance using the specified ledgerId, entryId,
partition and batchIndex.
+ /// </summary>
public MessageId(ulong ledgerId, ulong entryId, int partition, int
batchIndex)
=> Data = new MessageIdData
{
diff --git a/src/DotPulsar/MessageMetadata.cs b/src/DotPulsar/MessageMetadata.cs
index 23e0c7b..b9109e9 100644
--- a/src/DotPulsar/MessageMetadata.cs
+++ b/src/DotPulsar/MessageMetadata.cs
@@ -23,6 +23,9 @@ namespace DotPulsar
/// </summary>
public sealed class MessageMetadata
{
+ /// <summary>
+ /// Initializes a new instance of the message metadata builder.
+ /// </summary>
public MessageMetadata()
=> Metadata = new Internal.PulsarApi.MessageMetadata();
diff --git a/src/DotPulsar/ProducerOptions.cs b/src/DotPulsar/ProducerOptions.cs
index 7002742..d7373a1 100644
--- a/src/DotPulsar/ProducerOptions.cs
+++ b/src/DotPulsar/ProducerOptions.cs
@@ -26,6 +26,9 @@ namespace DotPulsar
/// </summary>
public static readonly ulong DefaultInitialSequenceId = 0;
+ /// <summary>
+ /// Initializes a new instance using the specified topic.
+ /// </summary>
public ProducerOptions(string topic)
{
InitialSequenceId = DefaultInitialSequenceId;
diff --git a/src/DotPulsar/ProducerState.cs b/src/DotPulsar/ProducerState.cs
index 44b3ff3..5bab409 100644
--- a/src/DotPulsar/ProducerState.cs
+++ b/src/DotPulsar/ProducerState.cs
@@ -14,11 +14,29 @@
namespace DotPulsar
{
+ /// <summary>
+ /// The possible states a producer can be in.
+ /// </summary>
public enum ProducerState : byte
{
+ /// <summary>
+ /// The producer is closed. This is a final state.
+ /// </summary>
Closed,
+
+ /// <summary>
+ /// The producer is connected.
+ /// </summary>
Connected,
+
+ /// <summary>
+ /// The producer is disconnected.
+ /// </summary>
Disconnected,
+
+ /// <summary>
+ /// The producer is faulted. This is a final state.
+ /// </summary>
Faulted
}
}
diff --git a/src/DotPulsar/ReaderOptions.cs b/src/DotPulsar/ReaderOptions.cs
index 3baa295..42e4f3c 100644
--- a/src/DotPulsar/ReaderOptions.cs
+++ b/src/DotPulsar/ReaderOptions.cs
@@ -31,6 +31,9 @@ namespace DotPulsar
/// </summary>
public static readonly bool DefaultReadCompacted = false;
+ /// <summary>
+ /// Initializes a new instance using the specified startMessageId and
topic.
+ /// </summary>
public ReaderOptions(MessageId startMessageId, string topic)
{
MessagePrefetchCount = DefaultMessagePrefetchCount;
diff --git a/src/DotPulsar/ReaderState.cs b/src/DotPulsar/ReaderState.cs
index 637fc3d..c62b547 100644
--- a/src/DotPulsar/ReaderState.cs
+++ b/src/DotPulsar/ReaderState.cs
@@ -14,12 +14,34 @@
namespace DotPulsar
{
+ /// <summary>
+ /// The possible states a reader can be in.
+ /// </summary>
public enum ReaderState : byte
{
+ /// <summary>
+ /// The reader is closed. This is a final state.
+ /// </summary>
Closed,
+
+ /// <summary>
+ /// The reader is connected.
+ /// </summary>
Connected,
+
+ /// <summary>
+ /// The reader is disconnected.
+ /// </summary>
Disconnected,
+
+ /// <summary>
+ /// The reader is faulted. This is a final state.
+ /// </summary>
Faulted,
+
+ /// <summary>
+ /// The reader has reached the end of the topic. This is a final state.
+ /// </summary>
ReachedEndOfTopic
}
}
diff --git a/src/DotPulsar/SubscriptionInitialPosition.cs
b/src/DotPulsar/SubscriptionInitialPosition.cs
index 63c2c3d..a5dc9e8 100644
--- a/src/DotPulsar/SubscriptionInitialPosition.cs
+++ b/src/DotPulsar/SubscriptionInitialPosition.cs
@@ -14,9 +14,19 @@
namespace DotPulsar
{
+ /// <summary>
+ /// Intial position at which the cursor will be set when subscribing.
+ /// </summary>
public enum SubscriptionInitialPosition : byte
{
+ /// <summary>
+ /// Consumption will start at the last message.
+ /// </summary>
Latest = 0,
+
+ /// <summary>
+ /// Consumption will start at the first message.
+ /// </summary>
Earliest = 1
}
}
diff --git a/src/DotPulsar/SubscriptionType.cs
b/src/DotPulsar/SubscriptionType.cs
index 9763f90..34c2061 100644
--- a/src/DotPulsar/SubscriptionType.cs
+++ b/src/DotPulsar/SubscriptionType.cs
@@ -14,11 +14,29 @@
namespace DotPulsar
{
+ /// <summary>
+ /// Subscription types the consumer can choose from when subscribing.
+ /// </summary>
public enum SubscriptionType : byte
{
+ /// <summary>
+ /// There can be only 1 consumer on the same topic with the same
subscription name.
+ /// </summary>
Exclusive = 0,
+
+ /// <summary>
+ /// Multiple consumers will be able to use the same subscription name
and the messages will be dispatched according to a round-robin rotation.
+ /// </summary>
Shared = 1,
+
+ /// <summary>
+ /// Multiple consumers will be able to use the same subscription name
but only 1 consumer will receive the messages.
+ /// </summary>
Failover = 2,
+
+ /// <summary>
+ /// Multiple consumers will be able to use the same subscription name
and the messages will be dispatched according to the key.
+ /// </summary>
KeyShared = 3
}
}
