EASP API 7.8.0

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:

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

Notes:


Method Summary
 java.util.List acquireParams(java.util.List formals, java.util.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(java.util.List substs, java.util.List free, java.util.List defaulted, java.util.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(java.lang.String substStr)
          Creates a substitution from the given string.
 java.util.List createSubstitutions(java.util.List substStrs)
          Creates a List of substitutions from the given list of strings representing substitutions.
 void createSubstitutions(java.util.List substStrs, java.util.List substsList)
          adds the Substitutions represented by the given list of strings to the given list.
 java.util.List createSubstitutions(java.lang.String[] substStrs)
          Creates the List of substitutions represented by the given array of strings.
 void createSubstitutions(java.lang.String[] substStrs, java.util.List substsList)
          Creates substitutions represented by the given array of strings and adds them to the given List of substitutions.
 

Method Detail

acquireParams

java.util.List acquireParams(java.util.List formals,
                             java.util.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(java.util.List substs,
              java.util.List free,
              java.util.List defaulted,
              java.util.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

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:

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(java.lang.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

java.util.List createSubstitutions(java.lang.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(java.lang.String[] substStrs,
                         java.util.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

java.util.List createSubstitutions(java.util.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(java.util.List substStrs,
                         java.util.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)

EASP API 7.8.0