Test beans for integration tests

The spring application context defines a test profile named integration-test whose beans are only added to the context when a test class activates the profile through the usage of the profile Id integration-test, e.g. @ActiveProfiles("integration-test"):

        <beans profile="integration-test" >                             
                <bean id="ObjectMotherCredentialProvider" class="com.alpha.testutils.ObjectMotherCredentialProvider" />
        </beans>

CoreFactory

The factory class can be created in two ways:

• Use the new operator.
• From the core Spring application context.

If the factory is created using the new operator its dependencies isn't injected:

• uninitializedPineappleCore
• uninitializedFileBasedCredentialProvider
• runtimeDirectoryResolver

The factory will at runtime validate whether the dependencies are resolved, if not the factory will load the core Spring application context and resolve them by if self.

The factory is idempotent in regard to creation to of core and provider instances since they are defined with default scope in the Spring context.

Encrypting credential passwords

Credential passwords should be encrypted. The goal of the design is to achieve:

• All credential passwords stored in memory should be encrypted.
• Passwords should only exist decrypted in memory when used by the core component to establish a session to a resource.
• All credential passwords stored on disk in the credentials.xml file should be encrypted.

The design realizes these use cases to support the encryption requirements:

When Initialize credential provider is performed: The credentials are loaded from the credentials.xml:

• A password without the prefix encrypted: is encrypted and stored in memory encrypted with the prefix.
• A password with the prefix encrypted: is read into memory. The password is decrypted to validate that value after the prefix is in fact a encrypted value. If the decryption succeeds then decrypted password is thrown away. If the decryption fails then the value after the prefix is interpreted as a unencrypted password, the password is encrypted and stored encrypted in memory with the prefix.
• If an unencrypted password was encountered then the credentials is written back to file:
  • To synchronize the in-memory representation and the file content.
  • To encrypt the unencrypted password immediately.

When Create credential is performed: The credential is created with the password is encrypted with the prefix encrypted: and stored in-memory encrypted. The configuration is saved to synchronize the in-memory representation and the file content. Encryption is handled from FileBasedCredentialProviderImpl which delegates the creation of CredentialInfo to a CredentialInfoFactory where the password is encrypted prior to storing it in the credential info.

When Update credential is performed: The credential is deleted and then a new credential is created. The password is encrypted with the prefix encrypted: and stored in-memory encrypted. The configuration is saved to synchronize the in-memory representation and the file content. Encryption is handled from FileBasedCredentialProviderImpl which delegates the creation of CredentialInfo to a CredentialInfoFactory where the password is encrypted prior to storing it in the credential info.

When Delete credential is performed: The credential is deleted. The configuration is saved to synchronize the in-memory representation and the file content.

When Get credential is performed: Decryption is done by delegating the Credential creation to the CredentialConfigurationMarshaller in this case the PasswordEncryptingCredentialConfigurationMarshallerImpl. The method is only invoked when the core component creates a session to a resource.

The FileBasedCredentialProviderImpl delegates the Load credentials and Save credentials to its configured mashaller which is PasswordEncryptingCredentialConfigurationMarshallerImpl. The marshaller handles the encryption cases described above and then delegates the loading, saving and mapping to the CredentialConfigurationMarshallerImpl. The result is that all encryption functionality can be isolated to two classes; PasswordEncryptingCredentialInfoFactoryImpl and PasswordEncryptingCredentialConfigurationMarshallerImpl.

PasswordEncryptingCredentialInfoFactoryImpl

Factory for creation of credential info objects with encrypted passwords. The factory supports creation of objects which implements the CredentialInfo interface. The factory creates objects of the type CredentialInfoImpl. When a credential info object is created the password is encrypted and prefixed with encrypted: prefix.

The factory is used by the PasswordEncryptingCredentialConfigurationMarshallerImpl class and the FileBasedCredentialProviderImpl class to support encryption of passwords in memory and on disk.

PasswordEncryptingCredentialConfigurationMarshallerImpl

The marshaller is the central class in the design to support encryption of credential passwords.

The marshaller delegates the main bulk of load, saving and mapping logic to the CredentialConfigurationMarshallerImpl class and only intercepts calls when encryption is required.

Encrypting the Jasypt master password

The symmetric encryption functionality used by PasswordEncryptingCredentialInfoFactoryImpl and PasswordEncryptingCredentialConfigurationMarshallerImpl to encrypt credential passwords is implemented through the usage of the Jasypt string encryptor StandardPBEStringEncryptor.

The encryptor is configured to receive its configuration from the configuration object FileBasedPasswordPBEConfigImpl. The configuration object implements the Jasypt PBEConfig interface which defines a configuration object for a StandardPBEStringEncryptor encryptor.

The configuration object implements this algorithm to resolve the password:

1. The directory for the credential provider password file is resolved from the runtime directory provider:
   1. If the system property pineapple.credentialprovider.password.file is set then its value is interpreted as the location of the file.
   2. If the system property isn't defined then the file is resolved to ${pineapple.home.dir}/conf/credentialprovider.password.
2. If the password file doesn't exists then the file is created with a random generated password which is created using UUID.randomUUID(). The password is written to the file using UTF-8 encoding.
3. The password is read from the file using UTF-8 encoding and returned.

Configuration of Jasypt in Spring

Encryption of credential passwords are implemented through usage of the Jasypt library.

The symmetric password encryptor StandardPBEStringEncryptor is used. The encryptor is configured in the spring configuration file with a fixed salt. The salt is required to be fixed to support usage of the encryptor across JVM restarts.

The password for the encryptor is resolved by the CredentialProviderPasswordEnvironmentPBEConfigImpl class which loads the password from an external password file (read the class description below for more details).

DirectoryBasedModuleRepositoryImpl

The repository administers a set of available modules resolved from the modules directory. The modules directory is resolved from the runtime directory provider.

The class is defined as a bean in the application context for the core component. The instance created by the the context is not initialized. The repository is initialized by invoking the initialize() method. This method can be invoked from clients to refresh to content of the repository.

ResourceRepositoryImpl

The repository administers the set of configured resources in the environment configuration.

The repository support resolution of resources using a wild card environment. The name of the wild card environment is *. The used algorithm of resolution of a resource is, e.g. get(E,R):

• if repository contains environment E and the resource R is defined in the environment then E.R is returned.
• if repository contains environment * and the resource R is defined in the environment then *.R is returned.
• if repository doesn't contain environment E then an exception is thrown.
• if repository doesn't contain resource E.R then an exception is thrown.

ResourceConfigurationMarshallerImpl

The marshaller supports mapping from the unmarshalled configuration classes to the internal representation using the info objects. It also support mapping from the info classes to the configuration class used for marshalling.

Finally it supports the save operation which enables the repository to save the resource configuration on updates to the repository.

Separation of the plugin repository interface into two parts

The overall interface for the plugin repository is split into interfaces, PluginRepository and PluginRuntimeRepository, to be able to include a public interface (e.g. PluginRepository) in the Administration API (exposed through the API project) and define a internal interface for the core core component (e.g. PluginRuntimeRepository) which contains implementation specific details for resolution and execution of plugins at runtime.

Inclusion of the implementation specific details (e.g. stuff like OXM marshallers) in the public interface would resulted in the inclusion of Spring Framework interfaces (e.g. again the OXM marshallers) in the API project. This would have bloated the dependency graph for the API project and this was deemed unwise and thus the interface was split into two.

PluginRepositoryImpl

The class is defined as a bean in the application context for the core component. The instance created by the the context is not initialized. The repository is initialized by invoking the method: PluginRepository.initialize( String[] pluginIds );. The method is invoked in the InitializePluginActivatorCommand.

The repository will only scan for plugins candidates in the packages which is defined in the collection of plugin id's supplied as arguments to the initialize(..). The actual scanning is delegated to the PluginCandidateScannerImpl.

After a list of plugin candidates have been identified and stored in a application context. Then each candidate is processed in turn by the PluginInitializerImpl which attempts to initialize the candidate as a plugin.

The repository support resolution of operations using a wild card operation. The name of the wild card operation is *. The used algorithm of resolution of an operation is, e.g. get(P,O):

• if repository contains plugin P is defined and operation for O is defined then P.O is returned.
• if repository contains plugin P is defined and operation for * is defined then P.* is returned.
• if repository doesn't contain plugin P then an exception is thrown.
• if repository doesn't contain operation P.O then an exception is thrown.

PluginNameGeneratorImpl

Implements the BeanNameGenerator interface. The class is used by the PluginCandidateScannerImpl during scanning of the class path for plugin candidates in the scanForPlugins(..) method to generate bean names for plugin candidates.

The class generates names of the form: plugin: package-name.

PluginCandidateScannerImpl

The class is used by the PluginRepositoryImpl to scan the class path for plugin candidates.

The scanner will only scan for plugins candidates in the packages which is defined in the collection of plugin id's supplied as arguments to the scanForPlugins(..). The scanning criteria's is defined as:

• Scan for classes with the @Plugin annotation.
• Scan the packages is supplied as arguments to the initialize(..) method.

The scanner returns the collection of identified plugin candidates stored as beans in a application context. The bean id's are generated by the PluginNameGeneratorImpl class.

PluginInitializerImpl

The class is used by the PluginRepositoryImpl to initialize plugin candidates into ready-to-use plugins.

The initializer initializes plugins from the metadata defined on the @Plugin..

The initializer initializes the plugin application context with plugin providers which provides access to the Pineapple runtime system. These providers are initialized:

• The execution info provider with bean id = "coreExecutionInfoProvider".
• The runtime directory provider with bean id = "coreRuntimeDirectoryProvider".
• The administration provider with bean id = "coreAdminitrationProvider".

ExecutionContextRepositoryImpl

Repository for storage of execution contexts. The execution context for an operation is stored and removed from the repository during execution by OperationTaskImpl.

The algorithm for looking up a execution context in get(ExecutionResult) is:

• Lookup context using the result object as argument.
• If the lookup failed, then inspect whether result object is root. If the result object is root return null.
• Get parent result object and invoke get(..) with the parent result as argument.

The repository is accessed during execution by the plugin providers:

• Execution info provider
• Variable substitution provider

ResultRepositoryImpl

When an operation is started by the core component then the repository is used to create a ExecutionInfo meta data object which described the executed operation. In addition to the meta data, the execution info object also contains a reference to the root ExecutionResult object which contains the state of the execution.

The result repository implements the role of subscriber in the publish-subscriber pattern. Subscribers are all the registered result listeners, which implements the ResultListener interface.

When a execution result changes it state all registered listeners are notified of the event. The notification is done by invoking the ResultListener.notify(ExecutionResultNotification notification) on each listener with the state changing result as argument.

Besides notifying all registered listeners, repository also captures the events for the executing operations. The event capture is used by the REST controller in the web application to be able to deliver updated results when polled by a client (e.g. a controlling Pineapple instance).

The repository is implemented with a fixed capacity to limit the amount for stored executions in the repository. The repository has capacity for a fixed number of completed executions and any number of running executions. The fixed number of completed executions is defined by the the hard coded constant CoreConstants.EXECUTION_HISTORY_CAPACITY which initially is set to 5.

AsyncOperationTaskImpl

The implementation of the asynchronous execution is implemented by the usage of the Spring annotation @Async:

    @Async
    @Override
    public void execute(ExecutionInfo info) {
          operationTask.execute(info);
    }

    @Override
    public ExecutionInfo execute(String operation, String environment, String module) {
          String message = messageProvider.getMessage("aot.unspported_method");
          throw new UnsupportedOperationException(message);
    }

    @Override
    public ExecutionInfo executeComposite(String operation, String environment, String module, String description, ExecutionResult result) {
          String message = messageProvider.getMessage("aot.unspported_method");
          throw new UnsupportedOperationException(message);
    }

The configuration of the underlying task executor is defined in the Spring application context com.alpha.pineapple.core-config.xml by the operationExecutor bean.

The class forwards requests to the OperationTaskImpl which implements synchronous execution of a operation.

Only the method execute(ExecutionInfo info) support asynchronous execution of an operation. The other two methods defined in the interface throws an UnsupportedOperationException.

ExecutionInfoProviderImpl

The object implements the interface ExecutionInfoProvider is used by plugins to look up runtime info.

The algorithm for looking up up runtime info in the ExecutionInfoProvider.get(ExecutionResult result) method is:

• Lookup up the execution context for the operation in the execution context repository. The result is used as argument. The execution context for an operation is registered in the context by the OperationTaskImpl.
• Lookup the execution info in the context. The result is used as argument. The execution info for an operation was registered in the context by the InitializeOperationCommand.
• If the lookup fails then a ExecutionInfoNotFoundException is thrown.

The class is made available to plugins through usage of the @Resource dependency injection with either the bean or field id "coreExecutionInfoProvider". The class is made available to the core component through definition in the core component application context.

ScheduledOperationConfigurationMarshallerImpl

Saves and load the set of scheduled operations to the configuration named "scheduled-operations.xml" within the Pineapple configuration directory.

ScheduledOperationRespositoryImpl

The repository implements scheduling of operations using the Spring ThreadPoolTaskScheduler.

The repository uses the ScheduledOperationConfigurationMarshallerImpl to load and save the set of scheduled operations.

DefaultOperationTriggerResolverImpl

Resolves whether a trigger should be executed. The resolution is based on the algorithm:

• If the value of the on-target-operation attribute is null.
• If the value of the on-target-operation attribute is empty.
• If the value of the on-target-operation attribute is the wild card value "*".
• If the value of the on-target-operation attribute is identical to the operation that the model was invoked with.
• If the value of the on-target-operation attribute is a list value and one of the values in the list is identical to the operation that the model was invoked with.

DefaultResultTriggerResolverImpl

Resolves whether a trigger should be executed. The resolution is based on the algorithm:

• If the value of the on-result attribute is null.
• If the value of the on-result attribute is empty.
• If the value of the on-result attribute is the wild card value "*".
• If the value of the on-result attribute is identical to the result that the model execution concluded with.
• If the value of the on-result attribute is a list value and one of the values in the list is identical to the result that the model execution concluded with.

DefaultRuntimeDirectoryProviderImpl

Default implementation of the RuntimeDirectoryProvider interface which is used to resolve the default resolve runtime directories where Pineapple will run from.

The class is made available to plugins through usage of the @Resource dependency injection with either the bean or field id coreRuntimeDirectoryProvider.

PluginActivatorImpl

The class is defined as a bean in the application context for the core component. The instance created by the the context is not initialized. The activator is initialized by invoking the method: PluginActivator.initialize( CredentialProvider provider, ResourceRepository resourceRepository, PluginRepository pluginRepository );.

The method is invoked in the InitializePluginActivatorCommand.

RetrySessionHandlerImpl

Enabling usage of the session handler as a Spring bean

Plugin operation classes are proxied at runtime by the RetrySessionHandlerImpl class. The session handler class implements session handling for an operation and retry logic.

To enable usage of the RetrySessionHandlerImpl as a Spring managed bean for a which a new instance (e.g. a Spring prototype bean) is created every time an operation is proxied, several beans are defined. The beans defined to support the usage of RetrySessionHandlerImpl are:

<bean id="unintializedRetrySessionHandler" class="com.alpha.pineapple.plugin.session.SessionRetryHandlerImpl" scope="prototype"/>
<bean id="springRetrySessionHandlerFactory" class="org.springframework.beans.factory.config.ObjectFactoryCreatingFactoryBean">
    <property name="targetBeanName">
        <idref local="unintializedRetrySessionHandler"/>
    </property>
</bean>

The springRetrySessionHandlerFactory bean is a factory for creation of Spring managed objects. The factory supports creation of instances of the referenced bean unintializedSessionHandler.

The unintializedRetrySessionHandler bean is defined to define a target object for the factory. The bean is defined as a prototype. It should NOT be used directly as a dependency.

Usage of the session handler factory

The session handler factory RetrySessionHandlerFactoryImpl is used by the PluginActivatorImpl to create session handler instances. The factory is referenced through is bean name retrySessionHandlerFactory.

SessionRetryListenerImpl

The listener class logs method retries and add the information to the registered execution result. The listener is able to differentiate between cause of the retry, e.g. whether it is caused by a connect, usage or disconnect error.

The class is defined as a bean named sessionRetryListener in the application context for the core component. The bean is registered with the RetryTemplate which implements the retry logic. The bean is registered as part of constructing a session proxy done by the SessionRetryProxyFactoryImpl class.

SessionRetryProxyFactoryImpl

Factory for creation of session retry proxy instances. The factory supports creation of JDK dynamic proxies using the Spring ProxyFactory. The proxy factory doesn't support creation of proxies for session classes with NO no-arg constructor (e.g. the defined constructors which requires arguments).

The factory creates the session proxy programmatically by:

• Creates a SessionRetryListenerImp instance and registers the execution result for the operation.
• Creates a RetryTemplate and registers the session retry listener.
• Creates a RretryOperationsInterceptor and registers the retry template.
• instruments the target session with the retryOperationsInterceptor bean.

Spring configuration of retry support

The core component application context defines retry support with these beans:

<bean id="sessionRetryProxyFactory" class="com.alpha.pineapple.plugin.session.retry.SessionRetryProxyFactoryImpl" />    
<bean id="sessionRetryListener" class=" com.alpha.pineapple.plugin.session.retry.SessionRetryListenerImpl" scope="prototype" />
<bean id="simpleRetryPolicy" class="org.springframework.retry.policy.SimpleRetryPolicy">
    <property name="maxAttempts" value="4"/>
</bean>
<bean id="exponentialBackOffPolicy" class="org.springframework.retry.backoff.ExponentialBackOffPolicy" >
    <property name="initialInterval" value="100"/>
    <property name="maxInterval" value="5000"/>
    <property name="multiplier" value="2"/>
</bean>    
<bean id="retryTemplate" class="org.springframework.retry.support.RetryTemplate" scope="prototype">
        <property name="retryPolicy" ref="simpleRetryPolicy" />
        <property name="backOffPolicy" ref="exponentialBackOffPolicy" />                
</bean>
<bean id="retryOperationsInterceptor" class="org.springframework.retry.interceptor.RetryOperationsInterceptor" scope="prototype">
</bean>
<bean id="springRetryTemplateFactory" class="org.springframework.beans.factory.config.ObjectFactoryCreatingFactoryBean">
        <property name="targetBeanName">
                <idref local="retryTemplate"/>
        </property>
</bean>
<bean id="sessionRetryListenerFactory" class="org.springframework.beans.factory.config.ObjectFactoryCreatingFactoryBean">
        <property name="targetBeanName">
                <idref local="sessionRetryListener"/>
        </property>
</bean>
<bean id="springRetryOperationsInterceptorFactory" class="org.springframework.beans.factory.config.ObjectFactoryCreatingFactoryBean">
        <property name="targetBeanName">
                <idref local="retryOperationsInterceptor"/>
        </property>
</bean>

The defined beans are:

• The sessionRetryProxyFactory bean enables usage of the sessionRetryProxyFactoryImpl class as a Spring managed bean.
• The sessionRetryListener bean enables usage of the SessionRetryListenerImpl class as a Spring managed bean.
• The simpleRetryPolicy bean configures the retry policy for the setup. A SimpleRetryPolicy is used which will trigger reinvocation of a failed method with a preset number of attempts. The policy is configured with 4 attempts. This will allow the retry support to capture three succesive exception and then a hopefully successful attempt.
• The exponentialBackOffPolicy bean defines a back off policy which calculates the pauses between attempts.
• The retryTemplate bean implements the Spring retry engine. It uses the retry policy and back off policy to directs its behavior.
• The retryOperationsInterceptor bean defines a AOP advice which is used on proxied classes. The advice intercepts all method invocations, including toString().
• The springRetryTemplateFactory bean enables programmatic creation of the Spring managed bean retryTemplate.
• The sessionRetryListenerFactory bean enables programmatic creation of the Spring managed bean sessionRetryListener.
• The springRetryOperationsInterceptorFactory bean enables programmatic creation of the Spring managed bean retryOperationsInterceptor.

CommandFacadeImpl

The facade object provides a facade for the command objects. Thus the facade has references to the commands objects. But the individual command objects also uses the facade to invoke other commands. Thus the command objects has references to the facade.

This introduces circular dependencies between the facade and the command objects.

To enable Spring to handle the circular dependencies, the command objects are on the facade set using using setter injection. The same applies to the usage of setter injection on the commands to set the facade.

InvokePluginsCommand

InvokeTriggersCommand

The command is used by the InvokePluginsCommand to execute trigger after execution of a module model.

The command resolves which triggers to execute from the candidate list using the resolvers DefaultOperationTriggerResolverImpl and DefaultResultTriggerResolverImpl.

ModelVariableSubstitutorImpl

Implements the ModelVariableSubstitutor interface and provides the variable substitution capabilities in models.

The main idea behind the variable substitution is to proxy the object graph which represents the marshalled XML model and to intercept all calls to the object graph:

• Calls which returns a String are processed for variables.
• Calls which return a non-immutable object, instead returns a proxy.
• Calls which return an immutable object are ignored, i.e the immutable eobject is returned.
• Calls which return an primitive are ignored, i.e the primitive is returned.

The responsibility of the ModelVariableSubstitutorImpl is to:

• Assemble the variable builders support lookup of variables defined in module descriptors, the model and in the resource properties:
  • Variables defined in the module descriptor are handled by an instance of the ModuleDescriptorVariablesBuilder
  • Variables defined in the model are handled by an instance of the ModelVariablesBuilder
  • Variables defined in the session resource properties are handled by an instance of the SessionVariablesBuilder
• Initialize the proxying of the model by initializing the proxy factory VariableSubstitutedProxyFactory.

VariableSubstitutionInterceptor

This class is a Spring AOP advice. It it used by the proxy factory VariableSubstitutedProxyFactoryImpl to intercept all method calls to objects which are proxied by JDK dynamic proxies.

When it intercepts a method it implements the algorithm:

• If the return type of the invoked method is a String then:
  • Invoke the object and get the returned string.
  • Process the string for variables.
  • Return the string.
• Otherwise:
  • Invoke the object and get the returned object.
  • Decorate the returned result with a new proxy, using the proxy factory to create to proxy, the and return the proxy.

CglibVariableSubstitutionInterceptorImpl

This class is a Spring CGLIB AOP advice. It it used by the proxy factory VariableSubstitutedProxyFactoryImpl to intercept all method calls to objects which are proxied by JDK dynamic proxies.

It implements the same algorithm as VariableSubstitutionInterceptor for variable processing.

VariableSubstitutedProxyFactoryImpl

Factory for creation of proxy instances depending on the implementation of the target class which should be proxied.

The factory implements the algorithm:

• If the target object is null then return null.
• If the target object is a string then process the string for variables and return the processed string.
• If the target object is immutable then return the target object unchanged.
• If the target object is a primitive then return the target object unchanged.
• If the target object is a private class then create a JDK dynamic proxy using the Spring ProxyFactory.
• Otherwise create a dynamic proxy using CGLIB. The actual creation of the proxy is done using Objenesis library to handle the case where the class doesn't have a no-arg constructor (e.g. the defined constructors which requires arguments). Objenesis is used since it supports object creation while the bypassing constructor(s).

ReflectionHelper

Provides helper functions for reflection based operations:

• createObject(..) which can instantiate objects using reflection, which take a single String as argument in the constructor.

ObjectMotherResourceRepository

Implementation of the ObjectMother pattern, provides helper functions for using resources repository in unit tests.

ObjectMotherCredentialProvider

Implementation of the ObjectMother pattern, provides helper functions using credentials providers in unit tests.

The class is also defined as a Spring bean in the integration test Spring configuration class IntegrationTestSpringConfig.

test-archive-on-classpath.jar

A JAR file containing a single example module. Used to test the CreateDefaultEnvironmentConfigurationCommand and UnpackArchiveCommand classes.