Package org.palladiosimulator.generator.fluent.usagemodel.factory

Class FluentUsageModelFactory

  • public class FluentUsageModelFactory
extends Object
    This class provides all the methods to create a UsageModel and create Entities that are added to this Repository. Characteristics of the entities are specified by method chaining.

    Start creating a repository like this: FluentUsageModelFactory create = new FluentUsageModelFactory();
    UsageModel usgModel = create.newUsageModel()

    //create datatypes, components, interfaces etc. here

    .createUsageModelNow();

     Refer to the project's Readme for an introduction and detailed examples.

    • Constructor Detail

      • FluentUsageModelFactory

        public FluentUsageModelFactory()
        Creates an instance of the FluentUsageModelFactory.

    • Method Detail

      • addSystem

        public FluentUsageModelFactory addSystem​(org.palladiosimulator.pcm.system.System system)
        Sets the System used in some objects of the usage model.
        Parameters:
        system - System
        Returns:
        FluentUsageModelFactory
        See Also:
        System

      • newUsageModel

        public IUsageModel newUsageModel()
        Creates a representation of the model object 'UsageModel'.

        The usageModel entity allows storing components, data types, and interfaces to be fetched and reused for construction of component instances as well as new component types.

        Returns:
        the UsageModel in the making
        See Also:
        UsageModel

      • newUsageScenario

        public UsageScenarioCreator newUsageScenario​(ScenarioBehaviourCreator scenarioBehavior,
                                             WorkloadCreator workload)
        Creates a new usage scenario.

        UsageScenarios are concurrently executed behaviours of users within one UsageModel. It describes which services are directly invoked by users in one specific use case and models the possible sequences of calling them. Each UsageScenario includes a workload and a scenario behaviour.

        Usage scenarios are defined by their name

        Parameters:
        scenarioBehavior - ScenarioBehaviourCreator
        workload - WorkloadCreator
        Returns:
        the usage scenario in the making
        See Also:
        UsageScenario

      • newUserData

        public UserDataCreator newUserData​(org.palladiosimulator.pcm.core.composition.AssemblyContext context)
        Creates a new user data creator.

        A representation of the model object 'User Data'. UserData characterises data used in specific assembly contexts in the system. This data is the same for all UsageScenarios, i.e.,multiple users accessing the same components access the same data. This UserData refers to component parameters of the system publicized by the software architect (see pcm::parameters package). The domain expert characterises the values of component parameters related to business concepts (e.g., user specific data,data specific for a business domain), whereas the software architect characterises the values of component parameters related to technical concepts (e.g., size of caches, size of a thread pool, configuration data,etc.). One UserData instance includes all parameter characterisation for the annotated entity.

        User Data offers the characteristics name and VariableUsage and needs a mandatory AssemblyContext

        Parameters:
        context - AssemblyContext
        Returns:
        the user data in the making
        See Also:
        UserData, VariableUsage, AssemblyContext

      • newScenarioBehavior

        public ScenarioBehaviourCreator newScenarioBehavior()
        Creates a new scenario behaviour.

        A representation of the model object 'Scenario Behaviour'. A ScenarioBehaviour specifies possible sequences of executing services provided by the system.It contains a set of AbstractUserActions, each referencing a predecessor and successor (except the first and last action), thereby forming a sequence of actions.See the AbstractAction documentation for why it is advantageous to model control flow in this way, as the same principle is used in the RDSEFF language.Concrete user actions of the usage model are:- Branch- Loop- EntryLevelSystemCall- Delay- Start- StopSo far, ScenarioBehaviours do not include forks in the user flow (i.e., splitting the flow with anAND semantic), as it is assumed that users always act sequentially.As there are no random variables depending on other variables in the usage model, there are no equivalent actions to GuardedBranchTransitions or CollectionIteratorActions.

        Scenario Behaviour offers the characteristics name and actions. The Actions are a chain of actions combined with an explicit start and end.

        Returns:
        the scenario behaviour in the making
        See Also:
        ScenarioBehaviour, AbstractUserAction

      • newBranchAction

        public BranchActionCreator newBranchAction()
        Creates a new branch action.

        A representation of the model object 'Branch'. A Branch splits the user flow with a XOR-semantic: one of the included BranchTransitionsis taken depending on the specified branch probabilities. Each BranchTransition contains a nested ScenarioBehaviour, which a user executes once this branch transition is chosen. After execution of the complete nested ScenarioBehaviour, the next action in the user flow after theBranch is its successor action.A constraint ensures that all branchProbabilities of the included BranchTransitions sum up to 1.

        A Branch offers the characteristics name, successor and BranchTransitions.

        Returns:
        the branch action in the making
        See Also:
        AbstractUserAction, Branch, BranchTransition

      • newBranchTransition

        public BranchTransitionCreator newBranchTransition​(ScenarioBehaviourCreator branchedBehaviour)
        Creates a new branch transition.

        A representation of the model object 'Branch Transition'. The BranchTransition is an association class that realises the containment of ScenarioBehaviours in in the branches of a Branch action. It is a separate meta class because it has the additional attribute branchProbability that specifies how probably it is that the references ScenarioBehaviour is executed in the Branch action.See also Branch.

        BranchTransition offers the characteristics branched behaviour, probability and needs a mandatory branchedBehaviour

        Parameters:
        branchedBehaviour - ScenarioBehaviourCreator
        Returns:
        the branch transition in the making
        See Also:
        AbstractUserAction, BranchTransition, ScenarioBehaviour

      • newDelayAction

        public DelayActionCreator newDelayAction​(String timeSpecification)
        Creates a new delay action.

        A representation of the model object 'Delay'. A Delay represents a timing delay as a RandomVariable between two user actions. The Delay is included into the usage model to express that users do not call system services in direct successions,but usually need some time to determine their next action. User delays are for example useful,if a performance analyst wants to determine the execution time for a complete scenario behaviour(instead of a single service), which needs to include user delays.

        Delay offers the characteristics name, successor and needs a mandatory time specification.

        Parameters:
        timeSpecification - String
        Returns:
        the delay action in the making
        See Also:
        AbstractUserAction, Delay

      • newEntryLevelSystemCall

        public EntryLevelSystemCallCreator newEntryLevelSystemCall​(OperationProvidedSignatureRole operationProvided)
        Creates a new entry level system call action. OperationProvidedSignatureRole is a class to function as structure for operation provided role and operation signature.

        A representation of the model object 'Entry Level System Call'. An EntryLevelSystemCall models the call to a service provided by a system. Therefore, anEntryLevelSystemCall references a ProvidedRole of a PCM System, from which the called interface and the providing component within the system can be derived, and a Signature specifying the called service. Notice, that the usage model does not permit the domain expert to model calls directly to components, but only to system roles. This decouples the System structure(i.e., the component-based software architecture model and its allocation) from the UsageModeland the software architect can change the System (e.g., include new components, remove existing components, or change their wiring or allocation) independently from the domain expert, if the system provided roles are not affected. EntryLevelSystemCalls may include a set of input parameter characterisations and a set of output parameter characterisations (as described in the pcm::parameters package). However, the random variables characterising the input parameters like NUMBER_OF_ELEMENTS can not depend on other variables in the usage model. They have to be composed from literals only including literals describing random variables having a certain fixed distribution.

        Entry level system call offers the characteristics name, successor, input parameter usage, output parameter usage and needs a mandatory operation provided role and related operation signature.

        Parameters:
        OperationProvidedSignatureRole - class as structure for operation provided role and operation signature
        Returns:
        the entry level system call action in the making
        See Also:
        AbstractUserAction, EntryLevelSystemCall, VariableUsage, OperationProvidedRole, OperationSignature

      • newLoopAction

        public LoopActionCreator newLoopAction​(String iteration,
                                       ScenarioBehaviourCreator bodyBehaviour)
        Creates a new loop action.

        A representation of the model object 'Loop'. A Loop models a repeated sequence of actions in the user flow. It contains a nested ScenarioBehaviour specifying the loop body, and a RandomVariable specifying the number of iterations.

        Loop offers the characteristics name, successor, and needs a mandatory iteration and body behaviour.

        Parameters:
        body - behaviour ScenarioBehaviourCreator
        iteration - the iteration
        Returns:
        the delay action in the making
        See Also:
        AbstractUserAction, Loop, ScenarioBehaviour

      • newStartAction

        public StartActionCreator newStartAction()
        Creates a new start action.

        A representation of the model object 'Start'. Each ScenarioBehaviour has exactly one Start action which marks the action where the control flows begins. Start actions have no predecessor.

        A Start offers the characteristics name and successor

        Returns:
        the start action in the making
        See Also:
        AbstractUserAction, Start

      • newStopAction

        public StopActionCreator newStopAction()
        Creates a new stop action.

        A representation of the model object 'Stop'. Each ScenarioBehaviour has exactly one Stop action which marks the action where the control flows ends. Stop actions have no successor.

        Stop offers the characteristics name

        Returns:
        the stop action in the making
        See Also:
        AbstractUserAction, Stop

      • newClosedWorkload

        public ClosedWorkloadCreator newClosedWorkload​(String thinkTime)
        Creates a new closed workload.

        A representation of the model object 'Closed Workload'. ClosedWorkload specifies directly the (constant) user population and a think time. It models that a fixed number of users execute their scenario, then wait (or think) for the specified amount of think time as a RandomVariable, and then reenter the system executing their scenario again.Performance analysts use closed workloads to model scenarios, where the number of users is known(e.g., a fixed number of users in a company).

        Closed Workload offers the characteristics population, and needs a mandatory think time.

        Parameters:
        thinkTime - String
        Returns:
        the closed workload in the making
        See Also:
        Workload, ClosedWorkload

      • newOpenWorkload

        public OpenWorkloadCreator newOpenWorkload​(String interArrivalTime)
        Creates a new open workload.

        A representation of the model object 'Open Workload'. OpenWorkload specifies usage intensity with an inter-arrival time (i.e., the time between two user arrivals at the system) as a RandomVariable with an arbitrary probability distribution. It models that an infinite stream of users arrives at a system. The users execute their scenario, and then leave the system. The user population (i.e., the number of users concurrently present in a system) is not fixed in an OpenWorkload.

        Open Workload needs a mandatory inter-arrival time.

        Parameters:
        interArrivalTime - String
        Returns:
        the open workload in the making
        See Also:
        Workload, OpenWorkload

      • newVariableUsage

        public VariableUsageCreator newVariableUsage​(String namespaceReference,
                                             String... innerReferences)
        Creates a new variable usage.

        A representation of the model object 'Variable Usage'. Variable usages are used to characterise variables like input and output variables or component parameters. They contain the specification of the variable as VariableCharacterisation and also refer to the name of the characterised variable in its namedReference association. Note that it was an explicit design decision to refer to variable names instead of the actual variables (i.e., by refering to Parameter class). It eased the writing of transformations (DSolver as well as SimuCom) but put some complexity in the frontend for entering the variable usages.

        Variable Usage offers the characteristics name, {@link org.palladiosimulator.generator.fluent.shared.components.VariableUsageCreator# withVariableCharacterisation(String,VariableCharacterisationType) variable characterisation} and needs a mandatory namespace reference and inner references.

        Parameters:
        namespaceReference - String
        innerReferences - String...
        Returns:
        the variable usage in the making
        See Also:
        VariableUsage, VariableCharacterisation, NamespaceReference

      • newVariableUsage

        public VariableUsageCreator newVariableUsage​(String variableReference)
        Creates a new variable usage.

        A representation of the model object 'Variable Usage'. Variable usages are used to characterise variables like input and output variables or component parameters. They contain the specification of the variable as VariableCharacterisation and also refer to the name of the characterised variable in its namedReference association. Note that it was an explicit design decision to refer to variable names instead of the actual variables (i.e., by referring to Parameter class). It eased the writing of transformations (DSolver as well as SimuCom) but put some complexity in the front end for entering the variable usages.

        Variable Usage offers the characteristics name, variable characterisation and needs a mandatory variable reference.

        Parameters:
        variableReference - String
        Returns:
        the variable usage in the making
        See Also:
        VariableUsage, VariableCharacterisation, VariableReference

      • fetchOffAssemblyContextByName

        public org.palladiosimulator.pcm.core.composition.AssemblyContext fetchOffAssemblyContextByName​(String systemName,
                                                                                                String assemblyName)
        Extracts the assembly context referenced by name from the system.

        This method throws a FluentApiException if no parameter is present under the given name. If more than one parameter with this name is present, the org.palladiosimulator.generator.fluent.usagemodel chooses the first parameter it finds.

        Parameters:
        systemName - name of the referenced system
        assemblyName - the name of the assembly context
        Returns:
        the assembly context
        See Also:
        AssemblyContext

      • fetchOffOperationRoleAndSignature

        public OperationProvidedSignatureRole fetchOffOperationRoleAndSignature​(String systemName,
                                                                        String operationProvidedRole,
                                                                        String operationSignature)
        Extracts the operation provided role referenced by operationProvidedRole from the system and the dependend operationSignature from the repository.

        This method throws a FluentApiException if no parameter is present under the given operationProvidedRole or operationSignature. If more than one parameter with the given Strings is present, the org.palladiosimulator.generator.fluent.usagemodel chooses each time the first parameter it finds.

        Parameters:
        systemName - the name of the referenced system
        operationProvidedRole - the name of the operation provided role
        operationSignature - the name if the operation signature
        Returns:
        Operation Provided Role & OperationSignature combined in one class
        See Also:
        OperationSignature, OperationProvidedRole, OperationProvidedSignatureRole