com.novell.ecb.secretstore
Class ReadSecret

java.lang.Object
  |
  +--com.novell.ecb.secretstore.SecretBean
        |
        +--com.novell.ecb.secretstore.ReadSecret

All Implemented Interfaces:

Command, java.io.Serializable

public class ReadSecret

extends SecretBean

Provides the functionality for reading an existing Secret.

The default behavior of this bean is to return the secret value that was last retrieved with doRefresh property set to true. In order to refresh the latest information about this secret in SecretStore, set doRefresh property to true explicitly.

Note: Admin cannot read other users' Secrets.

Required Input Properties:

ssInstance - A SecretStoreInstance object that represents the Secret to be read.

Optional Input Properties:

flags - The flags for the operation. Currently, no flag is defined for this operation. Property is provided here for future use.

enhancedProtectionPassword - Password for enhanced protected Secret. It is needed if Secret is enhanced protected with a password.

doRefresh Determines whether to get the fresh value from SecretStore. The default value is false.

Output Properties:

secretValue - A byte array containing Secret value. Default value is null.

Optional Output Properties:

sharedValue - A SharedValue object representing a SharedSecret's value. Default value is null.

Version:

1.0

See Also:

SharedValue, Serialized Form

Constructor Summary

ReadSecret()
Constructs a ReadSecret command bean.

ReadSecret(SecretInstance secretInstance)
Constructs a ReadSecret command bean and sets the SecretInstance to be used.

Method Summary

void	execute() Executes this command bean for reading the value of a Secret.
boolean	getDoRefresh() Returns the doRefresh property.
SSFlags	getFlags() Returns the flags set.
byte[]	getSecretValue() Returns the value of the Secret.
SharedValue	getSharedValue() Returns the value of a SharedSecret.
boolean	isReady() Tests whether the required input properties are set and the bean is in "initialized" state.
void	reset() Resets the output properties to the values they had before the execute method was called.
void	setDoRefresh(boolean doRefresh) Sets the doRefresh property.
void	setEnhancedProtectionPassword(char[] epPassword) Sets the enhanced protection password property.
void	setEnhancedProtectionPassword(java.lang.String epPassword) Deprecated. Replaced by setEnhancedProtectionPassword(char[]).
void	setFlags(SSFlags flags) Sets the flags to be used while reading Secrets.

Methods inherited from class com.novell.ecb.secretstore.SecretBean

getSecretInstance, setSecretInstance

Methods inherited from class java.lang.Object

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

Constructor Detail

ReadSecret

public ReadSecret()

Constructs a ReadSecret command bean.

ReadSecret

public ReadSecret(SecretInstance secretInstance)

Constructs a ReadSecret command bean and sets the SecretInstance to be used.

Parameters:

secretInstance - A SecretInstance object that represents the Secret to be read.

Method Detail

setFlags

public void setFlags(SSFlags flags)

Sets the flags to be used while reading Secrets.

Parameters:

flags - Flags for the operation. Currently, no flag is defined for this operation. Property is provided here for future use.

getFlags

public SSFlags getFlags()

Returns the flags set.

Returns:

SSFlags The flags set.

setDoRefresh

public void setDoRefresh(boolean doRefresh)

Sets the doRefresh property.

Parameters:

doRefresh - If set to false, cached value is returned. Set to true to get the latest value. Default value is false.

getDoRefresh

public boolean getDoRefresh()

Returns the doRefresh property.

Returns:

boolean True if latest values are read instead of cached values; else, returns False.

setEnhancedProtectionPassword

public void setEnhancedProtectionPassword(java.lang.String epPassword)

Deprecated. Replaced by setEnhancedProtectionPassword(char[]).

Sets the enhanced protection password property.

If this password is already set by GetSecretInstance bean, it is not required to set it again as it gets populated inside the SecretInstance object.

Parameters:

epPassword - EnhancedProtectionPassword for the Secret.

setEnhancedProtectionPassword

public void setEnhancedProtectionPassword(char[] epPassword)

Sets the enhanced protection password property.

If this password is already set by GetSecretInstance bean, it is not required to set it again as it gets populated inside the SecretInstance object.

Parameters:

epPassword - EnhancedProtectionPassword for the Secret.

isReady

public boolean isReady()

Tests whether the required input properties are set and the bean is in "initialized" state.

If the user does not set a value for optional input property, default value is used. Therefore, these properties do not affect the readiness of the bean. However, bean will not be in ready state if any of the required input properties is not set.

Returns:

boolean True if the bean is in initialized state; else, returns False.

reset

public void reset()

Resets the output properties to the values they had before the execute method was called.

Sets the output properties, secretValue and sharedValue, to their default values i.e. Null.

execute

public void execute()
             throws CommandException

Executes this command bean for reading the value of a Secret.

Throws:

CommandException - Thrown if the bean fails to execute.

Example 1: Shows how to use ReadSecret bean for reading an ordinary Secret.

     // Get the SecretInstance from GetSecretInstance or EnumerateSecrets bean.
   SecretInstance si = getSI.getSecretInstance();
   try
     {
         // Instantiate the command bean
       ReadSecret secretReader = new ReadSecret(si);
         // Set the input properties of the command bean
         // Set doRefresh to true to force bean to read the 
         // latest value of Secret, otherwise cached value is returned.
       secretReader.setDoRefresh(true);
         // Set the EnhancedProtectionPassword for an enhancedProtected 
         // Secret. It can be set in GetSecretInstance bean also.
         // It is enough to set it at one place.
       secretReader.setEnhancedProtectionPassword("epPassword".toCharArray());
         // Call the execute method of the command bean
       secretReader.execute();
         // Query the output properties of the command bean
       byte[] secretValue = secretReader.getSecretValue();
         // Do any further operation
       ..
       ..
     }
     catch(CommandException e)
      {
         // TODO: Handle exception
      }
 

Example 2: Shows how to use ReadSecret bean for reading a SharedSecret.

     // Get the SecretInstance from GetSecretInstance or EnumerateSecrets bean.
     // Depending on the secretID, GetSecretInstance bean creates the 
     // instance of the SecretInstance or SharedSecretInstance.
   SecretInstance si = getSI.getSecretInstance();
   try
     {
         // Instantiate the command bean
       ReadSecret secretReader = new ReadSecret(si);
         // Set the input properties of the command bean
         // Set doRefresh to true to force bean to read the 
         // latest value of Secret, otherwise cached value is returned.
       secretReader.setDoRefresh(true);
         // Set the EnhancedProtectionPassword for an enhancedProtected 
         // Secret. It can be set in GetSecretInstance bean also.
         // It is enough to set it at one place.
       secretReader.setEnhancedProtectionPassword("epPassword".toCharArray());
         // Call the execute method of the command bean
       secretReader.execute();
         // Query the output properties of the command bean
       SharedValue val = secretReader.getSharedValue();
         // Do further operations
       Iterator iter = val.keys();
       while(iter.hasNext())
            {
               String key = (String) iter.next();
               System.out.println(key + " = " + val.getValue(key));
            }
     }
     catch(CommandException e)
      {
         // TODO: Handle exception
      }
 

See Also:

EnumerateSecrets, GetSecretInstance

getSecretValue

public byte[] getSecretValue()

Returns the value of the Secret.

Returns:

byte[] Byte array containing the secret value.

getSharedValue

public SharedValue getSharedValue()

Returns the value of a SharedSecret.

Returns:

SharedValue SharedSecret value. Returns null, if the Secret is not a SharedSecret. The returned object does not provide a proper value, if value is not as per the format defined for SharedSecret.