net.juniper.smgt.lib.subst
Interface SubstEngine

public interface SubstEngine

This is the interface to an engine creating and analyzing sets of Substitutions. It includes methods to do the following things:

• create substitutions from strings, thoroughly checking the syntax and semantics of the subsitutions represented by the input strings
• acquire the values for a set of variables according to a list of substitutions in the specific to general order including evaluating expressions and diagnosing which variables have no values
• classifying variables in a set of substitutions into three sets: free (defined, but with no value), defaulted (defined with a default value), and fixed (defined with a fixed value)

For more information on Substitutions and parameter value acquisition, see the SDX Administration and Operations Guide.

Notes:

• unlike previous SDX releases, for runtime efficiency, these methods may wait to parse and validate substitutions until absolutely necessary. Methods in the net.juniper.smgt.lib.subst group may not immediately throw exceptions indicating syntax errors. Methods such as acquireParams(List,List) and classify(List,List,List,List) may throw exceptions indicating syntax errors where previously they would have been thrown earlier when substitutions were created. Use Substitution.validate() to explicitly validate substitutions
• uline previous SDX releases, the substution engine does not do any semantic or type consistency checking. So where methods in this interface may have previously thrown exceptions due to inconsistent use of types or type/value combinations, corresponding exceptions may now be thrown at runtime when the policy engine attempts to construct polices as a result of parameter acquisition.

Method Summary

List	acquireParams(List formals, List acquired) Given a List of parameters and a List of aquired Substitutions ordered from specific to general, returns a List of values for the formal parameters according to the acquired Substitutions.
void	classify(List substs, List free, List defaulted, List fixed) classifies the variables in the given list of Substitutions in specific to general order (including variables occuring in the value) into 3 classes: free, defaulted, and fixed.
Substitution	createSubstitution(String substStr) Creates a substitution from the given string.
List	createSubstitutions(List substStrs) Creates a List of substitutions from the given list of strings representing substitutions.
void	createSubstitutions(List substStrs, List substsList) adds the Substitutions represented by the given list of strings to the given list.
List	createSubstitutions(String[] substStrs) Creates the List of substitutions represented by the given array of strings.
void	createSubstitutions(String[] substStrs, List substsList) Creates substitutions represented by the given array of strings and adds them to the given List of substitutions.

Method Detail

acquireParams

List acquireParams(List formals,
                   List acquired)
                   throws SubstitutionFormatException

Given a List of parameters and a List of aquired Substitutions ordered from specific to general, returns a List of values for the formal parameters according to the acquired Substitutions. Once the substitions are aquired, this is the method called by net.juniper.smgt.sae.ent.im.Subscription#getAdministrativeValues(), net.juniper.smgt.sae.ent.im.Session#getOperationalValues(), and net.juniper.smgt.sae.ent.im.Session#getPolicyValues(). It is included here for informational and debugging purposes.

The parameters and values are represented as Substitutions. Only the variables in the parameters are considered, the values and types of the parameters are ignored. The values List contains substitutions of values for the corresponding variables in the parameters List as defined by the List of aquired substiutions. The order of the variables in the values List is the same as the order in the parameters List, so to find the value for the variable in the ith position in the parameters List, use the substitution in the ith position in the returned values List.

The values in the returned List are partially evaluated to remove subexpressions containing no variables. The subexpressions containing no variables in the value after all possible variable substitutions are performed is evaluated, converting to floating point if necessary, and the results, are inserted into the output value substitution for the variable. It is possible for the output value Substitutions to contain variables in the values. Use Substitution.isGrounding() and Substitution.getValVars() to test if the aquisition found specific values for the variables.

To make this clearer, here are some examples:

Params	Substs	Vals	Comment
[x]	[x:any=y, y:number=z+1, z:burst=16999]	[x:burst=17000]	Most specific type deduced from aquired substitutions
[x,y]	[x:any=y, y:number=z+1, z:burst=16999]	[x:burst=17000, y:burst=17000]	Variables in same order in params and values
[x]	[x=y, y=z+2*w, w=3]	[x=z+6]	the subexpression 2*3 gets evaluated to 6
[x]	[y=z]	[x=x]	x=x is the way the method indicates that there were no substitutions for the formal parameter x.

Parameters:

params - java.util.List a List of Substitutions indicating the variables to search for values for in the given List of aquired Substitutions.

substs - java.util.List the List of Substitutions from Substitution the acquisition path in specific to general order that is used to find the values for the parameters. The list may contain individual Substitutions, Lists of Substitutions, or Maps of variable names (as Strings) to Substitutions. When searching for a substituion for a variable, if sublist is encountered, the search continues in the same direction in the sublist. If a Map is encountered, the variable name is used to key into the map to determine if there is a substution for the variable.

Returns:

java.util.List a List of Substitutions indicating the actual values to use for the variables in the given List of parameters

Throws:

SubstitutionFormatException - thrown if

• there is a syntax error in the string used to create one of the substitutions
• there is a loop in an acquisition chain. For instance, aquiring x with [x=x+1] will fail because of the loop in x. Aquiring x with [x=y, y=z+2, z=y] will also fail because of the the loop on y.
• there is a problem evaluating a numeric expression as the result of an acquisition. For instance, aquiring x with [x = 22/y, y=z-2, z=2] will fail because of the division by zero error.

classify

void classify(List substs,
              List free,
              List defaulted,
              List fixed)
              throws SubstitutionFormatException

classifies the variables in the given list of Substitutions in specific to general order (including variables occuring in the value) into 3 classes: free, defaulted, and fixed.

After aquisition of substitutions, this is the method called by net.juniper.smgt.sae.ent.im.Substitutions#getFreeVariables(), net.juniper.smgt.sae.ent.im.Substitutions#getFixedVariables(), and net.juniper.smgt.sae.ent.im.Substitutions#getDefaultedVariables(). It is also used to determine the service parameters and default values by net.juniper.smgt.sae.ent.im.Service#getParameters().

If substs is the list of substitutions from the Service followed by the substitutions for the policy parameters followed by the list of substitutions for the global variables considered fixed, then the parameters params of the service are classify(substs, params, params, null). For instance, if

• the global variables are [!interface_speed:number, !any:network=0.0.0.0/0]
• the policy parameters are [inside:network, outside:network, qos:number]
• the service substitutions are [!inside=asp, !outside=dept, !qos=0.2*interface_speed, asp:network=any, dept:network]

then

    classify([!inside=asp, !outside=dept, !qos=0.2*interface_speed, asp:network=any, dept:network
              inside:network, outside:network, qos:number,
              !interface_speed:number, !any:network=0.0.0.0/0],
             params,
             params,
             null)
 

gives params = [asp:network=0.0.0.0/0, dept:network]. This means that asp is a parameter to the service with default value 0.0.0.0/0 and dept is a parameter with no default.

This method is included here for informational and debugging purposes.

In the following discussion, more general substitutions (those closer to the back of the input list) are described as above more specific substitutions (those closer to the front of the input list). The three classes are as follows:

• free-variables which have no substitution with a value in the input list. Members of free are of the form VarName:Roles
• defaulted-the varibles which have substitutions with values and no substitutions which are fixed in the input list. Members of defaulted are of the form VarName:Roles=Val where Val is the most specific value defined for the variable.
• fixed-variables which have a fixed substitution in the input list. Members of fixed are of the form !VarName:Roles=Val where Val is the most specific value for the variable above the most general place where it is fixed, or !VarName:Roles if there is no value for the variable above the most general place where it is fixed.

In all cases, the roles of the output substitution is the list of all roles the variable had in the input list of substitutions.

Parameters:

substs - java.util.List a list of Substitutions from the acquisition path. The list may contain individual Substitutions, Lists of Substitutions, or Maps of variable names (as Strings) to Substitutions. When classifying variables, if sublist is encountered, the classification contines in the same direction in the sublist. If a Map is encountered, the Substitutions in the Map are classified in an arbitrary order.

free - java.util.List the List to add the Substitutions for free variables to, or null if the free variables are not required

defaulted - java.util.List the List to add the Substitutions for defaulted variables to, or null if the defaulted variables are not required

fixed - java.util.List the List to add the Substitutions for fixed variables to, or null if the fixed variables are not required

Throws:

SubstitutionFormatException - there is a syntax error in the string used to create one of the substitutions

createSubstitution

Substitution createSubstitution(String substStr)
                                throws SubstitutionFormatException

Creates a substitution from the given string. Will accept strings in the SDX 4.3 and earlier substitution format if the net.juniper.smgt.lib.subst.aggressiveValidation is true. However, substitution strings that have different interpretations in the old and new formats will be interpreted in the new format. For instance, integer division (//) in the old format will be interpreted as the begining of the description in the new format and quoted variable names in the values of the old format will be interpreted as non-IPv4 addresses in the new format.

Parameters:

substStr - java.lang.String the string representing the substitution

Returns:

Substitution the substitution represented by the string

Throws:

SubstitutionFormatException - may be thrown if there is a error the syntax of the substitution string. For instance, "x = y+" may result in an exception because there is a syntax error

createSubstitutions

List createSubstitutions(String[] substStrs)
                         throws SubstitutionFormatException

Creates the List of substitutions represented by the given array of strings.

Parameters:

substStrs - java.lang.String[] an array of strings representing substitutions

Returns:

List a list of Substitutions represented by the input strings

Throws:

SubstitutionFormatException - thrown if there is a problem with the syntax or semanics of any of the substitution strings.

See Also:

createSubstitution(String)

createSubstitutions

void createSubstitutions(String[] substStrs,
                         List substsList)
                         throws SubstitutionFormatException

Creates substitutions represented by the given array of strings and adds them to the given List of substitutions.

Parameters:

substStrs - java.lang.String[] an array of strings representing substitutions

substsList - List a List of Substitutions to add the substitutions represented by the strings to

Throws:

SubstitutionFormatException - thrown if there is a problem with the syntax or semanics of any of the substitution strings.

See Also:

createSubstitution(String)

createSubstitutions

List createSubstitutions(List substStrs)
                         throws SubstitutionFormatException

Creates a List of substitutions from the given list of strings representing substitutions.

Parameters:

substStrs - List a List of strings representing substitutions

Returns:

List a list of Substitutions represented by the input strings

Throws:

SubstitutionFormatException - thrown if there is a problem with the syntax or semanics of any of the substitution strings.

See Also:

createSubstitution(String)

createSubstitutions

void createSubstitutions(List substStrs,
                         List substsList)
                         throws SubstitutionFormatException

adds the Substitutions represented by the given list of strings to the given list.

Parameters:

substStrs - List a List of Strings representing substitutions

substsList - List a List of Substitutions to add the substitutions represented by the input strings to

Throws:

SubstitutionFormatException - thrown if there is a problem with the syntax or semanics of any of the substitution strings.

See Also:

createSubstitution(String)