com.hazelcast.client.proxy

## Class ClientSemaphoreProxy

- java.lang.Object
- - com.hazelcast.client.spi.ClientProxy
  - - com.hazelcast.client.proxy.ClientSemaphoreProxy

- All Implemented Interfaces:
    DistributedObject, ISemaphore

      public class ClientSemaphoreProxy
      extends ClientProxy
      implements ISemaphore

  Proxy implementation of `ISemaphore`.

- - ### Field Summary

    - ### Fields inherited from class com.hazelcast.client.spi.ClientProxy

      `name`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ClientSemaphoreProxy(String serviceName, String objectId, ClientContext context)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `acquire()` Acquires a permit if one is available, and returns immediately, reducing the number of available permits by one.
    `void` | `acquire(int permits)` Acquires the given number of permits if they are available, and returns immediately, reducing the number of available permits by the given amount.
    `int` | `availablePermits()` Returns the current number of permits currently available in this semaphore.
    `int` | `drainPermits()` Acquires and returns all permits that are available at invocation time.
    `void` | `increasePermits(int increase)` Increases the number of available permits by the indicated amount.
    `boolean` | `init(int permits)` Tries to initialize this ISemaphore instance with the given permit count
    `protected com.hazelcast.client.impl.protocol.ClientMessage` | `invokeOnPartition(com.hazelcast.client.impl.protocol.ClientMessage req)`
    `protected <T> T` | `invokeOnPartition(com.hazelcast.client.impl.protocol.ClientMessage clientMessage, long invocationTimeoutSeconds)`
    `protected <T> ClientDelegatingFuture<T>` | `invokeOnPartitionAsync(com.hazelcast.client.impl.protocol.ClientMessage clientMessage, com.hazelcast.client.impl.clientside.ClientMessageDecoder clientMessageDecoder)`
    `protected <T> T` | `invokeOnPartitionInterruptibly(com.hazelcast.client.impl.protocol.ClientMessage clientMessage)`
    `protected <T> T` | `invokeOnPartitionInterruptibly(com.hazelcast.client.impl.protocol.ClientMessage clientMessage, long invocationTimeoutSeconds)`
    `protected void` | `onInitialize()` Called when proxy is created.
    `void` | `reducePermits(int reduction)` Reduces the number of available permits by the indicated amount.
    `void` | `release()` Releases a permit and increases the number of available permits by one.
    `void` | `release(int permits)` Releases the given number of permits and increases the number of available permits by that amount.
    `String` | `toString()`
    `boolean` | `tryAcquire()` Acquires a permit if one is available, and returns `true` immediately.
    `boolean` | `tryAcquire(int permits)` Acquires the given number of permits if they are available, and returns `true` immediately.
    `boolean` | `tryAcquire(int permits, long timeout, TimeUnit unit)` Acquires the given number of permits and returns `true`, if they become available during the given waiting time.
    `boolean` | `tryAcquire(long timeout, TimeUnit unit)` Acquires a permit and returns `true`, if one becomes available during the given waiting time and the current thread has not been interrupted.

    - ### Methods inherited from class com.hazelcast.client.spi.ClientProxy

      `deregisterListener, destroy, destroyLocally, destroyRemotely, equals, getClient, getConnectedServerVersion, getContext, getDistributedObjectName, getId, getName, getPartitionKey, getSerializationService, getServiceName, hashCode, invoke, invoke, invokeOnAddress, invokeOnPartition, invokeOnPartitionInterruptibly, onDestroy, onShutdown, postDestroy, preDestroy, registerListener, setContext, toData, toObject`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface com.hazelcast.core.ISemaphore

      `getName`

    - ### Methods inherited from interface com.hazelcast.core.DistributedObject

      `destroy, getPartitionKey, getServiceName`

- - ### Constructor Detail

    - #### ClientSemaphoreProxy

          public ClientSemaphoreProxy(String serviceName,
                                      String objectId,
                                      ClientContext context)

  - ### Method Detail

    - #### init

          public boolean init(int permits)

      Description copied from interface: `ISemaphore`
      Tries to initialize this ISemaphore instance with the given permit count
      Specified by:
        `init` in interface `ISemaphore`
      Parameters:
        `permits` - the given permit count
      Returns:
        true if initialization success. false if already initialized

    - #### acquire

          public void acquire()
                       throws InterruptedException

      Description copied from interface: `ISemaphore`
      Acquires a permit if one is available, and returns immediately, reducing the number of available permits by one.

      If no permit is available, then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of three things happens:

      - some other thread invokes one of the `ISemaphore.release()` methods for this semaphore and the current thread is next to be assigned a permit,
      - this ISemaphore instance is destroyed, or
      - some other thread interrupts the current thread.

      If the current thread:

      - has its interrupted status set on entry to this method; or
      - is interrupted while waiting for a permit,
      then `InterruptedException` is thrown and the current thread's interrupted status is cleared.
      Specified by:
        `acquire` in interface `ISemaphore`
      Throws:
        `InterruptedException` - if the current thread is interrupted

    - #### acquire

          public void acquire(int permits)
                       throws InterruptedException

      Description copied from interface: `ISemaphore`
      Acquires the given number of permits if they are available, and returns immediately, reducing the number of available permits by the given amount.

      If insufficient permits are available then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of three things happens:

      - some other thread invokes one of the `release` methods for this semaphore, the current thread is next to be assigned permits and the number of available permits satisfies this request,
      - or this ISemaphore instance is destroyed,
      - or some other thread interrupts the current thread.
      If the current thread:
      - has its interrupted status set on entry to this method, or
      - is interrupted while waiting for a permit,
      then `InterruptedException` is thrown and the current thread's interrupted status is cleared.
      Specified by:
        `acquire` in interface `ISemaphore`
      Parameters:
        `permits` - the number of permits to acquire
      Throws:
        `InterruptedException` - if the current thread is interrupted

    - #### availablePermits

          public int availablePermits()

      Description copied from interface: `ISemaphore`
      Returns the current number of permits currently available in this semaphore.

      This method is typically used for debugging and testing purposes.

      Specified by:
        `availablePermits` in interface `ISemaphore`
      Returns:
        the number of permits available in this semaphore

    - #### drainPermits

          public int drainPermits()

      Description copied from interface: `ISemaphore`
      Acquires and returns all permits that are available at invocation time.
      Specified by:
        `drainPermits` in interface `ISemaphore`
      Returns:
        the number of permits drained

    - #### reducePermits

          public void reducePermits(int reduction)

      Description copied from interface: `ISemaphore`
      Reduces the number of available permits by the indicated amount. This method differs from `acquire` as it does not block until permits become available. Similarly, if the caller has acquired some permits, they are not released with this call.
      Specified by:
        `reducePermits` in interface `ISemaphore`
      Parameters:
        `reduction` - the number of permits to reduce

    - #### increasePermits

          public void increasePermits(int increase)

      Description copied from interface: `ISemaphore`
      Increases the number of available permits by the indicated amount. If there are some threads waiting for permits to become available, they will be notified. Moreover, if the caller has acquired some permits, they are not released with this call.
      Specified by:
        `increasePermits` in interface `ISemaphore`
      Parameters:
        `increase` - the number of permits to increase

    - #### release

          public void release()

      Description copied from interface: `ISemaphore`
      Releases a permit and increases the number of available permits by one. If some threads in the cluster are blocked for acquiring a permit, one of them will unblock by acquiring the permit released by this call.

      If the underlying `ISemaphore` impl is the non-JDK compatible CP impl that is configured via `CPSemaphoreConfig` and fetched via `CPSubsystem`, then a thread can only release a permit which it has acquired before. In other words, a thread cannot release a permit without acquiring it first.

      Otherwise, which means the underlying impl is either the JDK compatible CP impl configured via `CPSemaphoreConfig` and fetched via `CPSubsystem`, or it is the old impl fetched via `HazelcastInstance.getSemaphore(String)`, there is no requirement that a thread that releases a permit must have acquired that permit by calling one of the `ISemaphore.acquire()` methods. A thread can freely release a permit without acquiring it first. In this case, correct usage of a semaphore is established by programming convention in the application.

      Specified by:
        `release` in interface `ISemaphore`

    - #### release

          public void release(int permits)

      Description copied from interface: `ISemaphore`
      Releases the given number of permits and increases the number of available permits by that amount. If some threads in the cluster are blocked for acquiring permits, they will be notified.

      If the underlying `ISemaphore` impl is the non-JDK compatible CP impl that is configured via `CPSemaphoreConfig` and fetched via `CPSubsystem`, then a thread can only release a permit which it has acquired before. In other words, a thread cannot release a permit without acquiring it first.

      Otherwise, which means the underlying impl is either the JDK compatible CP impl configured via `CPSemaphoreConfig` and fetched via `CPSubsystem`, or it is the old impl fetched via `HazelcastInstance.getSemaphore(String)`, there is no requirement that a thread that releases a permit must have acquired that permit by calling one of the `ISemaphore.acquire()` methods. A thread can freely release a permit without acquiring it first. In this case, correct usage of a semaphore is established by programming convention in the application.

      Specified by:
        `release` in interface `ISemaphore`
      Parameters:
        `permits` - the number of permits to release

    - #### tryAcquire

          public boolean tryAcquire()

      Description copied from interface: `ISemaphore`
      Acquires a permit if one is available, and returns `true` immediately. If no permit is available, returns `false` immediately.
      Specified by:
        `tryAcquire` in interface `ISemaphore`
      Returns:
        `true` if a permit was acquired, `false` otherwise

    - #### tryAcquire

          public boolean tryAcquire(int permits)

      Description copied from interface: `ISemaphore`
      Acquires the given number of permits if they are available, and returns `true` immediately. If the requested number of permits are not available, returns `false` immediately.
      Specified by:
        `tryAcquire` in interface `ISemaphore`
      Parameters:
        `permits` - the number of permits to acquire
      Returns:
        `true` if the permits were acquired, `false` otherwise

    - #### tryAcquire

          public boolean tryAcquire(long timeout,
                                    TimeUnit unit)
                             throws InterruptedException

      Description copied from interface: `ISemaphore`
      Acquires a permit and returns `true`, if one becomes available during the given waiting time and the current thread has not been interrupted. If a permit is acquired, the number of available permits in the `ISemaphore` instance is also reduced by one.

      If no permit is available, then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of three things happens:

      - some other thread releases a permit and the current thread is next to be assigned a permit,
      - or this ISemaphore instance is destroyed,
      - or some other thread interrupts the current thread,
      - or the specified waiting time elapses.

      Returns `true` if a permit is successfully acquired.

      Returns `false` if the specified waiting time elapses without acquiring a permit. If the time is less than or equal to zero, the method will not wait at all.

      If the current thread:

      - has its interrupted status set on entry to this method,
      - or is interrupted while waiting for a permit,
      then `InterruptedException` is thrown and the current thread's interrupted status is cleared.
      Specified by:
        `tryAcquire` in interface `ISemaphore`
      Parameters:
        `timeout` - the maximum time to wait for a permit
        `unit` - the time unit of the `timeout` argument
      Returns:
        `true` if a permit was acquired and `false` if the waiting time elapsed before a permit was acquired
      Throws:
        `InterruptedException` - if the current thread is interrupted

    - #### tryAcquire

          public boolean tryAcquire(int permits,
                                    long timeout,
                                    TimeUnit unit)
                             throws InterruptedException

      Description copied from interface: `ISemaphore`
      Acquires the given number of permits and returns `true`, if they become available during the given waiting time. If permits are acquired, the number of available permits in the `ISemaphore` instance is also reduced by the given amount.

      If no sufficient permits are available, then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of three things happens:

      - permits are released by other threads, the current thread is next to be assigned permits and the number of available permits satisfies this request,
      - or some other thread interrupts the current thread,
      - or the specified waiting time elapses.
      Returns `true` if requested permits are successfully acquired.

      Returns `false` if the specified waiting time elapses without acquiring permits. If the time is less than or equal to zero, the method will not wait at all.

      If the current thread:

      - has its interrupted status set on entry to this method,
      - or is interrupted while waiting for a permit,
      then `InterruptedException` is thrown and the current thread's interrupted status is cleared.
      Specified by:
        `tryAcquire` in interface `ISemaphore`
      Parameters:
        `permits` - the number of permits to acquire
        `timeout` - the maximum time to wait for the permits
        `unit` - the time unit of the `timeout` argument
      Returns:
        `true` if all permits were acquired, `false` if the waiting time elapsed before all permits could be acquired
      Throws:
        `InterruptedException` - if the current thread is interrupted

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### onInitialize

          protected void onInitialize()

      Description copied from class: `ClientProxy`
      Called when proxy is created. Overriding implementations can add initialization specific logic into this method like registering a listener, creating a cleanup task etc.
      Overrides:
        `onInitialize` in class `ClientProxy`

    - #### invokeOnPartition

          protected com.hazelcast.client.impl.protocol.ClientMessage invokeOnPartition(com.hazelcast.client.impl.protocol.ClientMessage req)

    - #### invokeOnPartitionInterruptibly

          protected <T> T invokeOnPartitionInterruptibly(com.hazelcast.client.impl.protocol.ClientMessage clientMessage)
                                                  throws InterruptedException

      Throws:
        `InterruptedException`

    - #### invokeOnPartitionAsync

          protected <T> ClientDelegatingFuture<T> invokeOnPartitionAsync(com.hazelcast.client.impl.protocol.ClientMessage clientMessage,
                                                                         com.hazelcast.client.impl.clientside.ClientMessageDecoder clientMessageDecoder)

    - #### invokeOnPartition

          protected <T> T invokeOnPartition(com.hazelcast.client.impl.protocol.ClientMessage clientMessage,
                                            long invocationTimeoutSeconds)

    - #### invokeOnPartitionInterruptibly

          protected <T> T invokeOnPartitionInterruptibly(com.hazelcast.client.impl.protocol.ClientMessage clientMessage,
                                                         long invocationTimeoutSeconds)
                                                  throws InterruptedException

      Throws:
        `InterruptedException`

Copyright © 2019. All rights reserved.