com.vordel.env

Class EnvironmentSettings

java.lang.Object

com.vordel.env.EnvironmentSettings

public class EnvironmentSettings
extends java.lang.Object

Utility class implementing operations relating to the the environmentalization of settings at group-level. The environment settings are held in the EnvSettingsStore.xml store in the Deployment Archive. This helper class is used by API Server, Policy Studio and Jython scripts.

Constructor Summary

Constructors

Constructor and Description
EnvironmentSettings(com.vordel.es.EntityStore store) Create an EnvironmentSettings from an entity store.

Method Summary

Methods

Modifier and Type	Method and Description
com.vordel.es.Entity	addEnviromentSetting(com.vordel.es.Entity entity, java.lang.String fieldname, int index) Add a new environmentalized field for an entity.
java.util.Map<com.vordel.es.ESPK,com.vordel.es.Entity>	applyEnvironmentSpecificValues() Apply the environment values in the env group settings component store to the store, i.e.
com.vordel.es.ESPK	findEnvironmentalizedEntity(com.vordel.es.Entity entity) Find an EnvironmentalizedEntity relating to an Entity in the entity store.
java.lang.String	getDisplayNameForPPK(com.vordel.es.ESPK pk) Used by promotion script to display user-friendly identifier for a string portable ESPK
java.lang.String	getDisplayNameForPPK(java.lang.String ppk) Used by promotion script to display user-friendly identifier for a string portable ESPK
com.vordel.es.ESPK	getEnvironmentalizedEntitiesPk(com.vordel.es.EntityStore store) Get the PK of the EnvironmentalizedEntities in the entiity store.
java.lang.Object	getEnvironmentSettingValue(com.vordel.es.Entity envFieldEntity) Called by promotion script/Policy Studio when an existing environment-specific value must be displayed to user so they can decide to override or not.
java.lang.String	getEnvironmentSettingValueAsString(com.vordel.es.Entity envFieldEntity) Called by promotion script when an existing environment-specific value must be displayed to user so they can decide to override or not.
EnvironmentalizedEntities	getEnvSettings() Get the environmentalized settings.
com.vordel.common.crypto.PasswordCipher	getPasswordCipher() Get the password cipher
java.util.List<com.vordel.es.ESPK>	getPossibleESPKValuesForReference(com.vordel.es.Entity entityToEnvironmentalize, com.vordel.es.Entity envFieldEntity) Used by promotion script to get a list of portable ESPKs that may be used as values for references, e.g.
java.util.List<java.lang.String>	getPossibleStringValuesForReference(com.vordel.es.Entity entityToEnvironmentalize, com.vordel.es.Entity envFieldEntity) Used by promotion script to get a list of portable ESPKs (as strings) that may be used as values for references, e.g.
java.lang.String	getReferenceType(com.vordel.es.Entity entityToEnvironmentalize, com.vordel.es.Entity envFieldEntity)
com.vordel.es.EntityStore	getStore() Get the entity store.
boolean	hasEnvironmentSetting(com.vordel.es.Entity entity, java.lang.String fieldname, int index) Determines whether an environmentalized field already exists.
java.util.Map<com.vordel.es.Entity,java.util.Collection<com.vordel.es.Entity>>	interpretEnvSettingsForStore() Generate a map with a key that is an entity in the server's main entity store, and the value is a list of EnvironmentalizedField entities in the env settings component store that apply to that entity in the server's main entity store.
boolean	isReferenceField(com.vordel.es.Entity entityToEnvironmentalize, com.vordel.es.Entity envFieldEntity) Returns true if the EnvironmentalizedField refers to a reference field in the server entity store.
void	mergeTemplateEnvSettings(com.vordel.es.EntityStore policyArchiveStore) Used by DeploymentArchive constructor that takes a PolicyArchive and EnvironmentArchive as parameters.
void	removeEnviromentalizedEntity(com.vordel.es.Entity envEntity) Remove all env settings for a particular entity.
void	removeEnviromentSetting(com.vordel.es.Entity entity, java.lang.String fieldname, int index) Removes an environmentalized field from an entity.
void	removeEnvSettingValues() This method removes the values from the EnvSettingsStore.
void	setEnvironmentSettingValue(com.vordel.es.Entity envFieldEntity, java.lang.Object value) Called by promotion script/Policy Studio when an environment-specific value entered by user must be saved to the EnvSettingsStore.xml.
void	setEnvironmentSettingValueAsString(com.vordel.es.Entity envFieldEntity, java.lang.String value) Called by promotion script when an environment-specific value entered by user must be saved to the EnvSettingsStore.xml.
void	setPassphrase(java.lang.String passphrase) Set the passphrase for encrypting data in EnvGroupSettings.xml entity store.
void	upgrade() This method is run *after* an upgrade has completed.

Methods inherited from class java.lang.Object

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

Constructor Detail

EnvironmentSettings

public EnvironmentSettings(com.vordel.es.EntityStore store)
                    throws com.vordel.es.EntityStoreException

Create an EnvironmentSettings from an entity store.

Parameters:

store - The federated entity store containing the EnvSettingsStore.xml entity store, or in some cases the EnvSettingsStore.xml entity store

Throws:

com.vordel.es.EntityStoreException

Method Detail

getStore

public com.vordel.es.EntityStore getStore()

Get the entity store.

Returns:

The entity store

setPassphrase

public void setPassphrase(java.lang.String passphrase)

Set the passphrase for encrypting data in EnvGroupSettings.xml entity store. This must be the same as the passphrase to encrypt the group configuration for a group of API Servers. If not set the passphrase defaults to "".

Parameters:

passphrase - The passphrase

getPasswordCipher

public com.vordel.common.crypto.PasswordCipher getPasswordCipher()

Get the password cipher

Returns:

The cipher

addEnviromentSetting

public com.vordel.es.Entity addEnviromentSetting(com.vordel.es.Entity entity,
                                        java.lang.String fieldname,
                                        int index)
                                          throws com.vordel.es.EntityStoreException

Add a new environmentalized field for an entity. The underlying env settings store is updated. Used by Policy Studio when a field is environmentalized via the Environmentalize view.

Parameters:

entity - The entity that we are adding an environmentalized field to

fieldname - The field name of the field in the entity being environmentalized

index - The index of the field being environmentalized. For multi-valued fields this may be > 0

Returns:

The EnvironmentalizedField entity that has been added to the EnvSettingsStore.xml

Throws:

com.vordel.es.EntityStoreException

removeEnviromentSetting

public void removeEnviromentSetting(com.vordel.es.Entity entity,
                           java.lang.String fieldname,
                           int index)
                             throws com.vordel.es.EntityStoreException

Removes an environmentalized field from an entity. The underlying env settings store is updated. Used by Policy Studio when a field is no longer environmentalized via the Environmentalize view.

Parameters:

entity - The entity that we are removing the environmentalized field from

fieldname - The field name of the field in the entity we no longer wish to environmetalize

index - The index of the field. For multi-valued fields this may be > 0

Throws:

com.vordel.es.EntityStoreException

hasEnvironmentSetting

public boolean hasEnvironmentSetting(com.vordel.es.Entity entity,
                            java.lang.String fieldname,
                            int index)
                              throws com.vordel.es.EntityStoreException

Determines whether an environmentalized field already exists. Used by Policy Studio to check whether a particular field has been previously environmentalized.

Parameters:

entity - The entity whose field we want to check

fieldname - The field name of the entity we want to check

Throws:

com.vordel.es.EntityStoreException

mergeTemplateEnvSettings

public void mergeTemplateEnvSettings(com.vordel.es.EntityStore policyArchiveStore)
                              throws java.io.IOException,
                                     com.vordel.es.EntityStoreException

Used by DeploymentArchive constructor that takes a PolicyArchive and EnvironmentArchive as parameters. Used by Configuration Studio/script at promotion time when a user opens a v2.pol file (new from downstream) and a v1.env file (from last deployment in current environment). The EnvSettingsStore.xml in the store wrapped by this class is merged with the one in the policyArchiveStore as follows:-

• Settings that exist in v1.env and v2.pol are shown with the v1.env value.
• Settings that exist in v1.env and do not exist in v2.pol are not shown. This environment setting has been deleted.
• Settings that do not exist in v1.env and do exist in v2.pol are shown with no value. This is a new environment setting, the user should enter an appropriate value.

Parameters:

policyArchiveStore - The federated store from the policy archive.

Throws:

java.io.IOException

com.vordel.es.EntityStoreException

removeEnvSettingValues

public void removeEnvSettingValues()
                            throws com.vordel.es.EntityStoreException

This method removes the values from the EnvSettingsStore. This is used when a Policy Archive is created as downstream values will not be passed upstream in the .pol.

Throws:

java.io.IOException

com.vordel.es.EntityStoreException

applyEnvironmentSpecificValues

public java.util.Map<com.vordel.es.ESPK,com.vordel.es.Entity> applyEnvironmentSpecificValues()
                                                                                      throws com.vordel.es.EntityStoreException

Apply the environment values in the env group settings component store to the store, i.e. the main API Server config. Used by API Server at server startup. May also be used by promotion scripts to generate the API Server's loadable config in order to check for unresolved references.

Returns:

Throws:

com.vordel.es.EntityStoreException

interpretEnvSettingsForStore

public java.util.Map<com.vordel.es.Entity,java.util.Collection<com.vordel.es.Entity>> interpretEnvSettingsForStore()
                                                                                                            throws com.vordel.es.EntityStoreException

Generate a map with a key that is an entity in the server's main entity store, and the value is a list of EnvironmentalizedField entities in the env settings component store that apply to that entity in the server's main entity store. Can be used by promotion script. The map contents may be used to iterate through all the entities that have environmentalized settings and prompt the user to enter values.

Returns:

The map

Throws:

com.vordel.es.EntityStoreException

getEnvironmentSettingValueAsString

public java.lang.String getEnvironmentSettingValueAsString(com.vordel.es.Entity envFieldEntity)
                                                    throws com.vordel.es.EntityStoreException,
                                                           java.security.GeneralSecurityException

Called by promotion script when an existing environment-specific value must be displayed to user so they can decide to override or not.

Parameters:

envFieldEntity - The EnvironmentalizedField entity in the EnvSettingsStore.xml that holds the field whose value we are getting.

Returns:

The value as a string

Throws:

com.vordel.es.EntityStoreException

java.security.GeneralSecurityException

getEnvironmentSettingValue

public java.lang.Object getEnvironmentSettingValue(com.vordel.es.Entity envFieldEntity)
                                            throws com.vordel.es.EntityStoreException,
                                                   java.security.GeneralSecurityException

Called by promotion script/Policy Studio when an existing environment-specific value must be displayed to user so they can decide to override or not.

Parameters:

envFieldEntity - The EnvironmentalizedField entity in the EnvSettingsStore.xml that holds the field whose value we are getting.

Returns:

The value as a string

Throws:

com.vordel.es.EntityStoreException

java.security.GeneralSecurityException

setEnvironmentSettingValueAsString

public void setEnvironmentSettingValueAsString(com.vordel.es.Entity envFieldEntity,
                                      java.lang.String value)
                                        throws com.vordel.es.EntityStoreException,
                                               java.security.GeneralSecurityException

Called by promotion script when an environment-specific value entered by user must be saved to the EnvSettingsStore.xml.

Parameters:

envFieldEntity - The EnvironmentalizedField entity in the EnvSettingsStore.xml that holds the field whose value we are setting.

value - The value to set

Throws:

com.vordel.es.EntityStoreException

java.security.GeneralSecurityException

setEnvironmentSettingValue

public void setEnvironmentSettingValue(com.vordel.es.Entity envFieldEntity,
                              java.lang.Object value)
                                throws com.vordel.es.EntityStoreException,
                                       java.security.GeneralSecurityException

Called by promotion script/Policy Studio when an environment-specific value entered by user must be saved to the EnvSettingsStore.xml.

Parameters:

envFieldEntity - The EnvironmentalizedField entity in the EnvSettingsStore.xml that holds the field whose value we are setting.

value - The value to set

Throws:

com.vordel.es.EntityStoreException

java.security.GeneralSecurityException

isReferenceField

public boolean isReferenceField(com.vordel.es.Entity entityToEnvironmentalize,
                       com.vordel.es.Entity envFieldEntity)

Returns true if the EnvironmentalizedField refers to a reference field in the server entity store. Used in promotion script.

Parameters:

entityToEnvironmentalize - The entity that is being environmentalized in main server config.

envFieldEntity - The EnvironmentalizedField entity in the EnvSettingsStore.xml that holds the env-specific value.

Returns:

True is reference

getReferenceType

public java.lang.String getReferenceType(com.vordel.es.Entity entityToEnvironmentalize,
                                com.vordel.es.Entity envFieldEntity)

getPossibleESPKValuesForReference

public java.util.List<com.vordel.es.ESPK> getPossibleESPKValuesForReference(com.vordel.es.Entity entityToEnvironmentalize,
                                                                   com.vordel.es.Entity envFieldEntity)
                                                                     throws com.vordel.es.EntityStoreException

Used by promotion script to get a list of portable ESPKs that may be used as values for references, e.g. certs, PGP key pairs and key pairs.

Parameters:

entityToEnvironmentalize - The entity that is being environmentalized in main server config.

envFieldEntity - The EnvironmentalizedField entity in the EnvSettingsStore.xml that holds the env-specific value.

Returns:

List of string portable ESPKs

Throws:

com.vordel.es.EntityStoreException

getPossibleStringValuesForReference

public java.util.List<java.lang.String> getPossibleStringValuesForReference(com.vordel.es.Entity entityToEnvironmentalize,
                                                                   com.vordel.es.Entity envFieldEntity)
                                                                     throws com.vordel.es.EntityStoreException

Used by promotion script to get a list of portable ESPKs (as strings) that may be used as values for references, e.g. certs, PGP key pairs and key pairs.

Parameters:

entityToEnvironmentalize - The entity that is being environmentalized in main server config.

envFieldEntity - The EnvironmentalizedField entity in the EnvSettingsStore.xml that holds the env-specific value.

Returns:

List of string portable ESPKs

Throws:

com.vordel.es.EntityStoreException

getDisplayNameForPPK

public java.lang.String getDisplayNameForPPK(java.lang.String ppk)
                                      throws com.vordel.es.EntityStoreException

Used by promotion script to display user-friendly identifier for a string portable ESPK

Parameters:

ppk - string portable ESPK

Returns:

Throws:

com.vordel.es.EntityStoreException

getDisplayNameForPPK

public java.lang.String getDisplayNameForPPK(com.vordel.es.ESPK pk)
                                      throws com.vordel.es.EntityStoreException

Used by promotion script to display user-friendly identifier for a string portable ESPK

Parameters:

pk - The ESPK

Returns:

Throws:

com.vordel.es.EntityStoreException

getEnvSettings

public EnvironmentalizedEntities getEnvSettings()
                                         throws com.vordel.es.EntityStoreException

Get the environmentalized settings. Called via Deployment REST API by Vordel Manager for read-only view of current environment settings.

Returns:

The env settings

Throws:

com.vordel.es.EntityStoreException

upgrade

public void upgrade()
             throws com.vordel.es.EntityStoreException,
                    java.security.GeneralSecurityException

This method is run *after* an upgrade has completed. It ensures that the env settings are valid for the upgraded entity store. For each EnvironmentalizedEntity instance in EnvSettingsStore.xml:-

• If the related entity cannot be found (i.e. entity referred to by "entityPk"), then the upgrade has removed it. Delete the EnvironmentalizedEntity and all its child EnvironmentalizedFields. This covers an upgrade where the entity type or entity instance has been removed.
• If the related entity is found we do the following for each EnvironmentalizedField:-
  • Check the "entityFieldName" exists in the type, if it does not then remove the EnvironmentalizedField. This covers an upgrade that deletes a field.
  • Check the "index" of the EnvironmentalizedField refers to an existing Value for the field in the entity that has been environmentalized, (i.e. entity referred to by "entityPk"). If it does not, remove the EnvironmentalizedField.
  • If a field is a reference then check the referred to entity exists, if it does not exist remove the "value" for the EnvironmentalizedField.
  • If a field is a reference then check the referred to entity is of the correct entity type or sub-type as expected by upgraded entity. If not remove the "value" for the EnvironmentalizedField.
  • If field type has changed, then remove old EnvironmentalizedField and create one of the correct type and set the value. This covers an upgrade that changes the type of a field (non-reference types) e.g. from string->integer. In some cases we cannot convert original EnvironmentalizedField value to new type so the "value" is not set, e.g. convert string "xyz" to integer.

Throws:

com.vordel.es.EntityStoreException

java.security.GeneralSecurityException

removeEnviromentalizedEntity

public void removeEnviromentalizedEntity(com.vordel.es.Entity envEntity)
                                  throws com.vordel.es.EntityStoreException

Remove all env settings for a particular entity.

Parameters:

envEntity - The EnvironmentalizedEntity to remove

Throws:

com.vordel.es.EntityStoreException

getEnvironmentalizedEntitiesPk

public com.vordel.es.ESPK getEnvironmentalizedEntitiesPk(com.vordel.es.EntityStore store)
                                                  throws com.vordel.es.EntityStoreException

Get the PK of the EnvironmentalizedEntities in the entiity store.

Parameters:

store - The entity store

Returns:

Throws:

com.vordel.es.EntityStoreException

findEnvironmentalizedEntity

public com.vordel.es.ESPK findEnvironmentalizedEntity(com.vordel.es.Entity entity)
                                               throws com.vordel.es.EntityStoreException

Find an EnvironmentalizedEntity relating to an Entity in the entity store.

Parameters:

entity - The entity

Returns:

Throws:

com.vordel.es.EntityStoreException