ControlVariableAccessor (IBM InfoSphere Streams Java Operator API)

Type Parameters:
T - Type of the variable.
```
public interface ControlVariableAccessor<T>
```
Operator access to a control variable. An operator control variable that is maintained as an MXBean in the Job Control Plane. This class maintains a local copy of the variable's value to reduce access cost, any change in the value in the MXBean results in an update to the value returned by getValue().
The value may be updated by:
- Any JMX client invoking the setting the value attribute for the MXBean in the Job Control Plane.
- An operator invoking setValue(Object) on their instance of ControlVariableAccessor.
An operator simply gets the value of the variable by calling getValue().
The control variable may be:
- Specific to an operator. The ObjectName for the control variable will be com.ibm.streams.control:type=controlvariable,name=variableName,operator=operatorName where variableName is getName() and operatorName is OperatorContext.getName()
- Shared across multiple operators in a job. The ObjectName for the control variable will be com.ibm.streams.control:type=controlvariable,name=variableName where variableName is getName()
The value is persisted by the Job Control Plane at the first update. Any initial value is not persisted, thus it is assumed that when the variable is shared, all operators have a common understanding of the initial value.

This class handles all the JMX interactions with the Job Control Plane including registering the MXBean and handling notifications. If this is a shared control variable then all operators that want to access the control variable create an instance of this interface with the same name and shared set to true.
Instances of this interface can be obtained using:
- ControlPlaneContext.createStringControlVariable(String, boolean, String) for a String control variable. This will result in a StringControlVariableMXBean being registered in the JCP.
Since:

InfoSphere® Streams Version 4.0

See Also:
ControlPlaneContext.createBooleanControlVariable(String, boolean, boolean), ControlPlaneContext.createDoubleControlVariable(String, boolean, double), ControlPlaneContext.createLongControlVariable(String, boolean, long), ControlPlaneContext.createStringControlVariable(String, boolean, String)

Method Summary

Methods
Modifier and Type	Method and Description
`java.lang.String`	`getName()` Get the name of this control variable.
`T`	`getValue()` Get the value of this control variable.
`javax.management.ObjectName`	`getVariableObjectName()` Get the `ObjectName` of this control variable's MXBean in the Job Control Plane Mbean server.
`void`	`setValue(T value)` Set this control variable to a new value.
`ControlVariableAccessor<T>`	`sync()` Synchronize this view of this control variable with the value in the Job Control Plane.

- Method Detail
  - getValue
```
T getValue()
```
    Get the value of this control variable. Returns the value without blocking.
    If this operator has not yet established a connection with the Job Control Plane then the initial value will be returned.
    If this operator has temporarily lost contact with the Job Control Plane then the most recent value obtained from the Job Control Plane will be returned.
    Otherwise the value returned is the current value of the control variable.
    To ensure the current value is returned then the caller may first call sync() to ensure a connection with the Job Control Plane is established.
    
    Returns:
    the value of this control variable.
  - setValue
```
void setValue(T value)
              throws java.io.IOException,
                     java.lang.InterruptedException
```
    Set this control variable to a new value. This call will block if the PE has not yet established a connection to the Job Control Plane. The new value is persisted in the Job Control Plane.
    
    Parameters:
    value - Value to set the control variable to.
    
    Throws:
    
    java.io.IOException - exception communicating with the Job Control Plane.
    
    java.lang.InterruptedException - Thread was interrupted waiting for a connection to the the Job Control Plane.
  - getName
```
java.lang.String getName()
```
    Get the name of this control variable.
    
    Returns:
    name of this control variable.
  - getVariableObjectName
```
javax.management.ObjectName getVariableObjectName()
```
    Get the ObjectName of this control variable's MXBean in the Job Control Plane Mbean server.
    
    Returns:
    ObjectName of this control variable's MXBean.
  - sync
```
ControlVariableAccessor<T> sync()
                                throws java.lang.InterruptedException
```
    Synchronize this view of this control variable with the value in the Job Control Plane. This call will return immediately if this operator is already connected to the Job Control Plane.
    Otherwise it will wait until a connection is established and getValue() represents the current value of this control variable.
    For example, this code creates a shared double control variable called threshold and then obtains its current value using the sync() method which may block.
```
 
    ControlPlaneContext cpc = context.getOptionalContext(ControlPlaneContext.class);
    ControlVariableAccessor<Double> thresholdVariable = cpc.createDoubleControlVariable("threshold", true, 100.0);
    
    // This will always get the current value of the
    // control variable, but may block waiting for
    // a connection to the Job Control Plane to
    // be established.
    double threshold = thresholdVariable.sync().getValue();
 
 
 
```
    Returns:
    this
    
    Throws:
    
    java.lang.InterruptedException - Thread was interrupted while waiting for the connection to the Job Control Plane to be established.
    Since:
    
    InfoSphere® Streams Version 4.1

getValue

setValue

getName

getVariableObjectName

sync