[Java] Update Cluster documentation around operations that require lo…

…oping until success.

aeron-cluster/src/main/java/io/aeron/cluster/service/Cluster.java

@@ -253,8 +253,18 @@ public static Role get(final AtomicCounter counter)
      * {@link ClusteredService#onSessionClose(ClientSession, long, CloseReason)}.
      * If applied to other events then they are not guaranteed to be reliable.
      * <p>
-     * Callers of this method must loop until the method succeeds, see {@link
-     * io.aeron.cluster.service.Cluster#scheduleTimer(long, long)} for an example.
+     * Callers of this method must loop until the method succeeds.
+     *
+     * <pre>{@code
+     * private Cluster cluster;
+     * // Lines omitted...
+     *
+     * cluster.idleStrategy().reset();
+     * while (!cluster.cancelTimer(correlationId))
+     * {
+     *     cluster.idleStrategy().idle();
+     * }
+     * }</pre>
      *
      * @param correlationId for the timer provided when it was scheduled. {@link Long#MAX_VALUE} not supported.
      * @return true if the request to cancel a timer has been sent or false if back-pressure is applied.
@@ -267,14 +277,14 @@ public static Role get(final AtomicCounter counter)
      * consensus module and have the cluster session of as the
      * {@link io.aeron.cluster.service.ClusteredServiceContainer.Configuration#SERVICE_ID_PROP_NAME}.
      * <p>
-     * Callers of this method should loop until the method succeeds.
+     * Callers of this method must loop until the method succeeds.
      *
      * <pre>{@code
      * private Cluster cluster;
      * // Lines omitted...
      *
      * cluster.idleStrategy().reset();
-     * do
+     * while(true)
      * {
      *     final long position = cluster.offer(buffer, offset, length);
      *     if (position > 0)
@@ -288,7 +298,6 @@ public static Role get(final AtomicCounter counter)
      *
      *     cluster.idleStrategy.idle();
      * }
-     * while (true);
      * }</pre>
      *
      * The cluster's idle strategy must be used in the body of the loop to allow for the clustered service to be
@@ -324,27 +333,36 @@ public static Role get(final AtomicCounter counter)
      * <p>
      * On successful claim, the Cluster session header will be written to the start of the claimed buffer section.
      * Clients <b>MUST</b> write into the claimed buffer region at offset + {@link AeronCluster#SESSION_HEADER_LENGTH}.
+     * <p>
+     * Callers of this method must loop until the method succeeds.
+     *
      * <pre>{@code
-     *     final DirectBuffer srcBuffer = acquireMessage();
+     * private final BufferClaim bufferClaim = new BufferClaim();
+     * private Cluster cluster;
+     * // Lines omitted...
      *
-     *     if (cluster.tryClaim(length, bufferClaim))
+     * final DirectBuffer srcBuffer = acquireMessage();
+     * cluster.idleStrategy().reset();
+     * while(true)
+     * {
+     *     final long position = cluster.tryClaim(length, bufferClaim);
+     *     if (position > 0)
      *     {
-     *         try
-     *         {
-     *              final MutableDirectBuffer buffer = bufferClaim.buffer();
-     *              final int offset = bufferClaim.offset();
-     *              // ensure that data is written at the correct offset
-     *              buffer.putBytes(offset + AeronCluster.SESSION_HEADER_LENGTH, srcBuffer, 0, length);
-     *         }
-     *         finally
-     *         {
-     *             bufferClaim.commit();
-     *         }
+     *         final MutableDirectBuffer buffer = bufferClaim.buffer();
+     *         final int offset = bufferClaim.offset();
+     *         // ensure that data is written after the session header
+     *         buffer.putBytes(offset + AeronCluster.SESSION_HEADER_LENGTH, srcBuffer, 0, length);
+     *         bufferClaim.commit();
+     *         break;
      *     }
+     *     else if (Publication.ADMIN_ACTION != position && Publication.BACK_PRESSURED != position)
+     *     {
+     *         throw new ClusterException("Internal tryClaim failed: " + position);
+     *     }
+     *
+     *     cluster.idleStrategy.idle();
+     * }
      * }</pre>
-     * <p>
-     * Callers of this method should loop until the method succeeds, see
-     * {@link io.aeron.cluster.service.Cluster#offer(DirectBuffer, int, int)} for an example.
      *
      * @param length      of the range to claim, in bytes.
      * @param bufferClaim to be populated if the claim succeeds.