Skip to content

Commit

Permalink
Creating some amount of javadocs
Browse files Browse the repository at this point in the history
  • Loading branch information
vladimir.bukhtoyarov committed May 7, 2015
1 parent bd52efe commit bb7cf7b
Show file tree
Hide file tree
Showing 2 changed files with 128 additions and 10 deletions.
120 changes: 112 additions & 8 deletions src/main/java/com/github/bucket4j/BucketBuilder.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,56 +29,156 @@

import java.io.Serializable;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.concurrent.TimeUnit;

import static com.github.bucket4j.BucketExceptions.nullTimeMetter;

/**
* A builder for buckets. Builder can be reused, i.e. one builder can create multiple buckets with similar configuration.
*
* @see com.github.bucket4j.local.LockFreeBucket
* @see com.github.bucket4j.grid.GridBucket
*/
public final class BucketBuilder {

private TimeMeter timeMeter = TimeMeter.SYSTEM_NANOTIME;
private List<BandwidthDefinition> bandwidths = new ArrayList<>(1);

/**
* Creates a builder for buckets
*
* @param timeMeter object which will measure time.
*/
public BucketBuilder(TimeMeter timeMeter) {
if (timeMeter == null) {
throw nullTimeMetter();
}
this.timeMeter = timeMeter;
}

/**
* Constructs an instance of {@link com.github.bucket4j.local.LockFreeBucket}
*
* @see com.github.bucket4j.local.LockFreeBucket
*/
public Bucket build() {
BucketConfiguration configuration = createConfiguration();
return new LockFreeBucket(configuration);
}

public Bucket buildHazelcast(IMap<Object, GridBucketState> map, Serializable key) {
/**
* Constructs an instance of {@link com.github.bucket4j.grid.GridBucket} which responsible to limit rate inside Hazelcast cluster.
*
* @param imap distributed map which will hold bucket inside cluster.
* Feel free to store inside single {@code imap} as mush buckets as you need.
* @param key for storing bucket inside {@code imap}.
* If you plan to store multiple buckets inside single {@code imap}, then each bucket should has own unique {@code key}.
*
* @see com.github.bucket4j.grid.hazelcast.HazelcastProxy
*/
public Bucket buildHazelcast(IMap<Object, GridBucketState> imap, Serializable key) {
BucketConfiguration configuration = createConfiguration();
return new GridBucket(configuration, new HazelcastProxy(map, key));
}

public BucketConfiguration createConfiguration() {
return new BucketConfiguration(this.bandwidths, timeMeter);
}

return new GridBucket(configuration, new HazelcastProxy(imap, key));
}

/**
* Constructs an instance of {@link com.github.bucket4j.grid.GridBucket} which responsible to limit rate inside Apache Ignite(GridGain) cluster.
*
* @param cache distributed cache which will hold bucket inside cluster.
* Feel free to store inside single {@code cache} as mush buckets as you need.
* @param key for storing bucket inside {@code cache}.
* If you plan to store multiple buckets inside single {@code cache}, then each bucket should has own unique {@code key}.
*
* @see com.github.bucket4j.grid.ignite.IgniteProxy
*/
public Bucket buildIgnite(IgniteCache<Object, GridBucketState> cache, Object key) {
BucketConfiguration configuration = createConfiguration();
return new GridBucket(configuration, new IgniteProxy(cache, key));
}

/**
* Constructs an instance of {@link com.github.bucket4j.grid.GridBucket} which responsible to limit rate inside Oracle Coherence cluster.
*
* @param cache distributed cache which will hold bucket inside cluster.
* Feel free to store inside single {@code cache} as mush buckets as you need.
* @param key for storing bucket inside {@code cache}.
* If you plan to store multiple buckets inside single {@code cache}, then each bucket should has own unique {@code key}.
*
* @see com.github.bucket4j.grid.coherence.CoherenceProxy
*/
public Bucket buildCoherence(NamedCache cache, Object key) {
BucketConfiguration configuration = createConfiguration();
return new GridBucket(configuration, new CoherenceProxy(cache, key));
}

/**
* Build distributed bucket for custom grid which is not supported out of the box.
*
* @param gridProxy delegate for accessing to your grid.
*
* @see com.github.bucket4j.grid.GridProxy
*/
public Bucket buildCustomGrid(GridProxy gridProxy) {
HashMap map;
BucketConfiguration configuration = createConfiguration();
return new GridBucket(configuration, gridProxy);
}

/**
* Adds guaranteed bandwidth for all buckets which will be constructed by this builder instance.
* <p>
* Guaranteed bandwidth provides following feature: if tokens can be consumed from guaranteed bandwidth,
* then bucket4j do not perform checking of any limited bandwidths.
* <p>
* Unlike limited bandwidths, you can use only one guaranteed bandwidth per single bucket.
* <p>
* Rate(which calculated as {@code maxCapacity/(timeUnit*period)}) of guaranteed bandwidth should be strongly lesser then rate of any limited bandwidth,
* else you will get {@link java.lang.IllegalArgumentException} during construction of bucket.
* <p>
* <pre>
* {@code
* // Adds bandwidth which guarantees, that client of bucket will be able to consume 1 tokens per 10 minutes,
* // regardless of limitations.
* withGuaranteedBandwidth(1, TimeUnit.MINUTES, 10);
* }
* </pre>
*
* @param maxCapacity the maximum capacity of bandwidth
* @param timeUnit Unit for period.
* @param period Period of bandwidth.
*
*/
public BucketBuilder withGuaranteedBandwidth(long maxCapacity, TimeUnit timeUnit, long period) {
return withGuaranteedBandwidth(maxCapacity, timeUnit, period, maxCapacity);
}

/**
* Adds guaranteed bandwidth for all buckets which will be constructed by this builder instance.
* <p>
* Guaranteed bandwidth provides following feature: if tokens can be consumed from guaranteed bandwidth,
* then bucket4j do not perform checking of any limited bandwidths.
* <p>
* Unlike limited bandwidths, you can use only one guaranteed bandwidth per single bucket.
* <p>
* Rate(which calculated as {@code maxCapacity/(timeUnit*period)}) of guaranteed bandwidth should be strongly lesser then rate of any limited bandwidth,
* else you will get {@link java.lang.IllegalArgumentException} during construction of bucket.
* <p>
* <pre>
* {@code
* // Adds bandwidth which guarantees, that client of bucket will be able to consume 1 tokens per 10 minutes,
* // regardless of limitations. Size of bandwidth is 0 after construction
* withGuaranteedBandwidth(2, TimeUnit.MINUTES, 1, 0);
* }
* </pre>
*
* @param maxCapacity the maximum capacity of bandwidth
* @param timeUnit Unit for period.
* @param period Period of bandwidth.
* @param initialCapacity initial capacity of bandwidth.
*
*/
public BucketBuilder withGuaranteedBandwidth(long maxCapacity, TimeUnit timeUnit, long period, long initialCapacity) {
final long bandwidthPeriod = timeMeter.toBandwidthPeriod(timeUnit, period);
final BandwidthDefinition bandwidth = new BandwidthDefinition(maxCapacity, initialCapacity, bandwidthPeriod, true);
Expand Down Expand Up @@ -119,6 +219,10 @@ public TimeMeter getTimeMeter() {
return timeMeter;
}

public BucketConfiguration createConfiguration() {
return new BucketConfiguration(this.bandwidths, timeMeter);
}

@Override
public String toString() {
return "BucketBuilder{" +
Expand Down
18 changes: 16 additions & 2 deletions src/main/java/com/github/bucket4j/Buckets.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,18 +17,32 @@

package com.github.bucket4j;

/**
* Entry point for bucket builder.
*/
public final class Buckets {

/**
* Creates instance of {@link com.github.bucket4j.BucketBuilder} which will create buckets with {@link com.github.bucket4j.TimeMeter#SYSTEM_NANOTIME} as time meter.
*/
public static BucketBuilder withNanoTimePrecision() {
return new BucketBuilder(TimeMeter.SYSTEM_NANOTIME);
}

/**
* Creates instance of {@link com.github.bucket4j.BucketBuilder} which will create buckets with {@link com.github.bucket4j.TimeMeter#SYSTEM_MILLISECONDS} as time meter.
*/
public static BucketBuilder withMillisTimePrecision() {
return new BucketBuilder(TimeMeter.SYSTEM_MILLISECONDS);
}

public static BucketBuilder withCustomTimePrecision(TimeMeter timeMeter) {
return new BucketBuilder(timeMeter);
/**
* Creates instance of {@link com.github.bucket4j.BucketBuilder} which will create buckets with {@code customTimeMeter} as time meter.
*
* @param customTimeMeter object which will measure time.
*/
public static BucketBuilder withCustomTimePrecision(TimeMeter customTimeMeter) {
return new BucketBuilder(customTimeMeter);
}

}

0 comments on commit bb7cf7b

Please sign in to comment.