Package org.apache.shiro.crypto.hash

Class HashRequest.Builder

java.lang.Object

org.apache.shiro.crypto.hash.HashRequest.Builder

Enclosing interface:

HashRequest

public static class HashRequest.Builder
extends Object

A Builder class representing the Builder design pattern for constructing HashRequest instances.

Since:

1.2

See Also:

SimpleHashRequest

Constructor Summary

Constructors

Constructor	Description
Builder()	Default no-arg constructor.

Method Summary

Modifier and Type	Method	Description
HashRequest	build()	Builds a HashRequest instance reflecting the specified configuration.
HashRequest.Builder	setAlgorithmName(String algorithmName)	Sets the name of the hash algorithm the HashService should use when computing the Hash.
HashRequest.Builder	setIterations(int iterations)	Sets the number of requested hash iterations to be performed when computing the final Hash result.
HashRequest.Builder	setSalt(Object salt)	Sets a salt to be used by the HashService during hash computation.
HashRequest.Builder	setSalt(ByteSource salt)	Sets a salt to be used by the HashService during hash computation.
HashRequest.Builder	setSource(Object source)	Sets the source data that will be hashed by a HashService.
HashRequest.Builder	setSource(ByteSource source)	Sets the source data that will be hashed by a HashService.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Builder

public Builder()

Default no-arg constructor.

Method Detail

setSource

public HashRequest.Builder setSource(ByteSource source)

Sets the source data that will be hashed by a HashService. For example, this might be a ByteSource representation of a password, or file, etc.

Parameters:

source - the source data that will be hashed by a HashService.

Returns:

this Builder instance for method chaining.

See Also:

HashRequest.getSource(), setSource(Object)

setSource

public HashRequest.Builder setSource(Object source)
                              throws IllegalArgumentException

Sets the source data that will be hashed by a HashService.

This is a convenience alternative to setSource(ByteSource): it will attempt to convert the argument into a ByteSource instance using Shiro's default conversion heuristics (as defined by ByteSource.Util.isCompatible. If the object cannot be heuristically converted to a ByteSource, an IllegalArgumentException will be thrown.

Parameters:

source - the byte-backed source data that will be hashed by a HashService.

Returns:

this Builder instance for method chaining.

Throws:

IllegalArgumentException - if the argument cannot be heuristically converted to a ByteSource instance.

See Also:

HashRequest.getSource(), setSource(ByteSource)

setSalt

public HashRequest.Builder setSalt(ByteSource salt)

Sets a salt to be used by the HashService during hash computation.

NOTE: not calling this method does not necessarily mean a salt won't be used at all - it just means that the request didn't include a salt. The servicing HashService is free to provide a salting strategy for a request, even if the request did not specify one. You can always check the result Hash getSalt() method to see what the actual salt was (if any), which may or may not match this request salt.

Parameters:

salt - a salt to be used by the HashService during hash computation

Returns:

this Builder instance for method chaining.

See Also:

HashRequest.getSalt()

setSalt

public HashRequest.Builder setSalt(Object salt)
                            throws IllegalArgumentException

Sets a salt to be used by the HashService during hash computation.

This is a convenience alternative to setSalt(ByteSource): it will attempt to convert the argument into a ByteSource instance using Shiro's default conversion heuristics (as defined by ByteSource.Util.isCompatible. If the object cannot be heuristically converted to a ByteSource, an IllegalArgumentException will be thrown.

Parameters:

salt - a salt to be used by the HashService during hash computation.

Returns:

this Builder instance for method chaining.

Throws:

IllegalArgumentException - if the argument cannot be heuristically converted to a ByteSource instance.

See Also:

setSalt(ByteSource), HashRequest.getSalt()

setIterations

public HashRequest.Builder setIterations(int iterations)

Sets the number of requested hash iterations to be performed when computing the final Hash result. Not calling this method or setting a non-positive value (0 or less) indicates that the HashService's default iteration configuration should be used. A positive value overrides the HashService's configuration for a single request.

Note that a HashService is free to ignore this number if it determines the number is not sufficient to meet a desired level of security. You can always check the result Hash getIterations() method to see what the actual number of iterations was, which may or may not match this request salt.

Parameters:

iterations - the number of requested hash iterations to be performed when computing the final Hash result.

Returns:

this Builder instance for method chaining.

See Also:

HashRequest.getIterations()

setAlgorithmName

public HashRequest.Builder setAlgorithmName(String algorithmName)

Sets the name of the hash algorithm the HashService should use when computing the Hash. Not calling this method or setting it to null indicates the the default algorithm configuration of the HashService should be used. A non-null value overrides the HashService's configuration for a single request.

Note that a HashService is free to ignore this value if it determines that the algorithm is not sufficient to meet a desired level of security. You can always check the result Hash getAlgorithmName() method to see what the actual algorithm was, which may or may not match this request salt.

Parameters:

algorithmName - the name of the hash algorithm the HashService should use when computing the Hash, or null if the default algorithm configuration of the HashService should be used.

Returns:

this Builder instance for method chaining.

See Also:

HashRequest.getAlgorithmName()

build

public HashRequest build()

Builds a HashRequest instance reflecting the specified configuration.

Returns:

a HashRequest instance reflecting the specified configuration.