Coordination State Machine

// CoordinationStateMachine.ump
// This UML state machine diagram in Umple is for the
// bCMS car crash management system
// See http://cserg0.site.uottawa.ca/cma2012/CaseStudy.pdf
// and http://www.cs.colostate.edu/remodd/v1/content/repository-model-driven-development-remodd-overview
// Author: Timothy C. Lethbridge

/* 
 * State machine for co-ordination of the
 * crisis, as seen from one SC. If  
 * communication is operating properly the
 * other coordinators' state machines will
 * generally be in the same states and
 * substates.
 *
 * Modelled given Section 4 of the requirements
 * This is a mixin to class crisis.
 */
class Crisis {

  // Number of ms allowed to negotiate routes,  
  // establish credentials
  Integer timeoutInMs = 20000;
  
  // True if we are the initiator of the crisis 
  // request, false otherwise
  Boolean thisSideInitiator;
  Boolean thisSideInitiatorOfTermination;
  
  Boolean routeAgreedYet;
  
  // True of we are the PSC, false of we are  
  // the FSC
  Boolean police;

  // Top level state machine
  crisisCoordinationStage {
  
    // 0. When initiated the crisis is in 
    // noCrisis state
    // It has been created but not yet 
    // populated, awaiting initiation
    // of coordination and data..
    noCrisis {
      entry / {setThisSideInitiator(false);}
      // We are initiating and requesting the 
      // other side to respond
      initiateCrisis / {
        setThisSideInitiator(true);
        sendInitiateCrisisRequestToOtherSC(); 
        } -> establishingCommunication;

      // We are responding to a request from 
      // the other SC 
      receiveInitiateCrisisRequest -> 
        establishingCommunication;
    }
    
    // 1. Establish communication and 
    // identification when a crisis begins
    establishingCommunication {
      entry / {sendSecureCredentials();}
      secureCredentialsConfirmed -> 
        managingCrisis;
      
      // Return to idle after some delay if 
      // other side initiated and did not
      // respond. It might have been a 
      // hacker. Alternatively if there is a
      // real crisis, normal manual processes 
      // would happen.
      after (timeoutInMs) 
        [!isThisSideInitiator()] -> noCrisis;
    }

    // Managing crisis involves continually 
    // exchanging information
    // Negotiating or renegotiating routes and 
    // other crisis details
    // These are handled concurrently.
    managingCrisis {
      // A crisis is underway. We initially 
      // start with empty data
      // which will be populated over time
      entry / {initiateEmptyCrisis(); }
    
      // 2,4,5,6. Exchanging details about what 
      // each knows about the crisis
      // So the information each coordinator 
     // has is the same.
      exchangingDetails {
        // Requirement Scenario 2
        ourUpdateToCrisisData
          / {sendCrisisData();}
          -> exchangingDetails;
        receiveCrisisData
          / {updateCrisisData();}
          -> exchangingDetails;
        
        // Requirement Scenario 4
        ourVehicleDispatched
          / {sendVehicleDispatch();}
          -> exchangingDetails;
        receiveVehicleDispatched
          / {updateTheirDispatch();}
          -> exchangingDetails;
        
        // Requirement Scenario 5
        ourVehicleArrived
          / {sendVehicleArrived();}
          -> exchangingDetails;
        receiveVehicleArrived
          / {updateTheirArrival();}
          -> exchangingDetails;
        
        // Requirement Scenario 6
        ourVehicleMetObjective
          / {sendVehicleMetObjective();}
          -> exchangingDetails;
        receiveMetObjective
        / {updateTheirMetObjective();}
        -> exchangingDetails;
        
        // Requirement 5.a - breakdown
        breakdown / {dispatchAndUpdateOther();} 
          -> exchangingDetails;
        
        // Requirement 5.b - 
        // congestion/blockage
        // TO DO
        
        // Requirement 5.c escalate crisis - 
        // renegotiate routes
        // TO DO
        
        
      } // End of exchangingDetails
        //concurrent substate
      ||
      
      // 7. Both parties must agree to close 
      // the crisis; either can initiate
      crisisEndManagement {
      
        // Normal substate of crisisEndManagement - no end in sight yet
        ongoingCrisis {
        
          // We could initiate termination
          initiateTermination / {
            setThisSideInitiatorOfTermination(true);
            sendTerminationRequestToOtherSC();
            } -> waitingForTerminationConfirmation;
          receiveTerminationRequestFromOtherSC 
          -> 
            waitingForUserTerminationAgreement;
        }
        
        waitingForUserTerminationAgreement {
          do {confirmWithUserToTerminate();}
          confirmTermination -> tearDown;
          after (timeoutInMs) -> ongoingCrisis;
        }
            
        // Substate of where we are waiting for 
        // the other end to agree
        waitingForTerminationConfirmation {
          receiveTerminationConfirmation
            -> tearDown;
          
          // If the other side has not agreed, 
          // we keep the crisis active
          after (timeoutInMs) -> ongoingCrisis;
        }
        
        // End of crisis
        tearDown {
          entry / {deleteCrisis();}
          -> noCrisis;
        }
      } // End of crisisEndManagement 
        // concurrent substate
      ||

      // 3. Negotiating route plan
      negotiatingRoutePlan {
    
        // Negotiation happens in parallel with 
        // reporting timeout
        negotiation {
          entry / {setRouteAgreedYet(false);}
          informOfNumberOfVehicles
            / {sendNumberOfVehicles();}
            -> negotiation;
          receiveNumberOfVehicles [isPolice()] 
            -> planningRoute;
          receiveRouteProposal [!isPolice()]
            -> approvingRoute;
          
          // Requirement 3.3.a2.a1
          receiveNoAgreeableRoute
            [!isPolice()] -> noRouteAgreement;
          
          // The PSC plans the route -- only 
          // PSC can be in this state
          planningRoute {
             do {planRoute();}
             routePlanComplete
               / {sendPlanToFSC(); }
               -> awaitingRouteApproval;
             
             // Requirement 3.3.a2.a1 - no more 
             // possible routes
             noMoreRoutes
               / {sendNoMoreRoutesToFSC(); }
               -> noRouteAgreement;
          }

          // The FSC approves the route  -- 
          // only FSC can be in this state
          approvingRoute {
            do {userConfirmRouteAcceptable();}
            routeAcceptable
              / {sendApprovalToPSC();}
              -> routeAgreed;
            routeUnacceptable
              / {sendDisapprovalToFSC();}
              -> negotiation;
          }
          
          // The PSC awaits for approval from 
          // the FSC. Only the PSC can be in 
          // this state
          awaitingRouteApproval {
            receiveApprovalFromFSC
              -> routeAgreed;
            
            // Requirement 3.3.a - FSC 
            // disagrees
            receiveDisapprovalFromFSC / {
              addRouteToDisapprovedChoices(); 
              } -> planningRoute;
          }
          
          routeAgreed {
            entry / {setRouteAgreedYet(true);}
          }
          
          noRouteAgreement {
             // requirement 3.3.a2.a1
          }
        } // End of Negotiation concurrent 
          // substate of negotiatingRoutePlan
        ||
        managingTimeliness {
          timeAcceptable {
            // Requirement 3.a1. Negotiations 
            // are taking excessive time
            after (timeoutInMs)
              [!isRouteAgreedYet()]
              -> timeUnacceptable;
          }
          timeUnacceptable {
            // Although negotiations may yet 
            // complete, we are going to send
            // out our own vehicles because too 
            // much time has passed
            do {
              promptAndLogReasonForTimeout(); }
          }
        } // End of managingTimeiness 
          //concurrent substate of 
          // negotiatingRoutePlan
      } // End of NegotiatingRoutePlan 
        //concurrent substate
    } // End of Managing Crisis top level state
  } // End of crisisCoordinationStage state 
    // machine
} // End of state machine mixin for 
  // Crisis