STAMP/STPA

Get facet model

All STAMP/STPA models and presentations exist in the STAMP/STPA facet Model which can be accessed by calling getFacet(String symbolicName)of ProjectAccessor.

public IFacet getSTAMPFacet(ProjectAccessor projectAccessor) throws ProjectNotFoundException {
    return projectAccessor.getFacet(IStampFacet.FACET_SYMBOLIC_NAME);
}

Get Models and Presentations

Get Models

Control Action

Let’s get control actions from Component1 in the sample control structure diagram below.

common_view_diagram_editor

This is how Astah API works in this case.
Control Actions cannot be got from Component1 directly. Control Links with Control Actions connected to Component1 must be got at first.

common_diagram_showing_class_structure

This is the instance diagram. As you can see, you can get Control Link from StpaAnalysis (IStpaAnalysis#getLinks().
Control Actions can be get from Control Link IControlLink#getActions().

common_instance_diagram

public List<IControlAction> getControlActions(IComponent component) throws ClassNotFoundException {
    List<IControlAction> controlActions = new ArrayList<>();
    IFacet facet =  AstahAPI.getAstahAPI().getProjectAccessor().getFacet(IStampFacet.FACET_SYMBOLIC_NAME);
    IStpaAnalysis analysis = facet.getRootElement(IStpaAnalysis.class);
    List<ILink> links = analysis.getLinks();
    for (ILink link : links) {
        if (link instanceof IControlLink && (((IControlLink) link).getSource() == component
                || ((IControlLink) link).getTarget() == component)) {
            controlActions.addAll(((IControlLink) link).getActions());
        }
    }
    return controlActions;
}

ProvidingCondition of ControlAction of UCA

Use IUnsafeControlAction.getControlAction to get ControlAction of UCA.
Use ISignal.getProvidingCondition to get ProvidingCondition because IControlAction generalizes ISignal.

public String getProvidingCondition(IUnsafeControlAction uca) {
    return uca.getControlAction().getProvidingCondition();
}

Get Diagrams and Presentations

Get Control Structure Diagram

public List<IControlStructureDiagram> getControlStructureDiagrams(IFacet facet) {
    IStpaAnalysis analysis = facet.getRootElement(IStpaAnalysis.class);
    List<IControlStructureDiagram> controlStructureDiagrams = new ArrayList<>();
    for (IDiagram diagram : analysis.getDiagrams()) {
        if (diagram instanceof IControlStructureDiagram) {
            controlStructureDiagrams.add((IControlStructureDiagram) diagram);
        }
    }
    return controlStructureDiagrams;
}

Get UCA Table of Control Structure Diagram

Use StampDiagramEditor to get UCA Table of Control Structure Diagram. UCA Table can be created if there is no identified one of Control Structure Diagram.

public IUCATable createOrGetUCATable(IControlStructureDiagram controlStructureDiagram, String ucaTableName) 
throws ClassNotFoundException, InvalidUsingException, InvalidEditingException {
    IDiagramEditorFactory diagramEditorFactory = AstahAPI.getAstahAPI().getProjectAccessor().getDiagramEditorFactory();
    StampDiagramEditor stampDiagramEditor = diagramEditorFactory.getDiagramEditor(StampDiagramEditor.class);
    return stampDiagramEditor.createOrGetUCATable(controlStructureDiagram, ucaTableName);
}

Get all nested component presentations in selected component presentation

Let’s get all nested component presentations from parent component in the sample control structure diagram below. common_view_diagram_editor

You can get nested component presentatons from parent component presentation with INodePresentation.getChildren.

public INodePresentation[] getChildrenComponentPresentation(
        IControlStructureDiagram controlStructureDiagram) throws InvalidUsingException {
    for (IPresentation presentation : controlStructureDiagram.getPresentations()) {
        IElement model = presentation.getModel();
        if (presentation instanceof INodePresentation && model instanceof IComponent
                && "parent component".equals(((IComponent) model).getName())) {
            return ((INodePresentation) presentation).getChildren();
        }
    }
    return new INodePresentation[0];
}

Edit Models and Presentations

In order to edit models or presentations using API, you need the transaction process. Also an exception will happen if:

  • The project is not registered in the project accessor or
  • The edition for the API is not correct or
  • target models/presentations you are trying to edit are non-editable

Edit model

Model Editor

The StampModelEditor is to used when you edit STAMP/STPA model with API.
For example, A Control Action can be created from StampModelEditor.
If you edit a model that can have multiple presentations, you can create/edit from each Model Editor.

Editting Model Viewpoint

Model Editors Model elements you can create in the Model Editor
StampModelEditor Component,Control Action,Control Link,Feedback,Feedback Link,Process Model,Process Variable,Process Value,Precondition,Accident,Hazard,Safety Constraint,UCA,Non UCA,HazardCausalFactor,Hazard Scenario

Create Hazard with SafetyConstraint for Accident

// Transaction processing is required
public IHazard createHazard(IAccident accident, String hazardDescription) throws InvalidEditingException {
    IModelEditorFactory modelEditorFactory =  projectAccessor.getModelEditorFactory();
    StampModelEditor stampModelEditor = modelEditorFactory.getModelEditor(StampModelEditor.class);
    IFacet facet = projectAccessor.getFacet(IStampFacet.FACET_SYMBOLIC_NAME);
    IStpaAnalysis analysis = facet.getRootElement(IStpaAnalysis.class);

    IHazard hazard = stampModelEditor.createHazard(analysis,
            Collections.singletonList(accident), hazardDescription);
    ISafetyConstraint safetyConstraint1 = stampModelEditor.createSafetyConstraint(analysis,
            Collections.singletonList(hazard), "safetyConstraint1");
    ISafetyConstraint safetyConstraint2 = stampModelEditor.createSafetyConstraint(analysis,
            Collections.singletonList(hazard), "safetyConstraint2");
    return hazard;
}

Create UCA for Control Action

Let’s create UCA1 for Control Action and Not Providing GuideWord cell in the sample UCA Table below.
common_view_diagram_editor

This is the instance diagram.
common_instance_diagram

// Transaction processing is required
public IUnsafeControlAction createUCA(IStpaAnalysis analysis) throws ClassNotFoundException, InvalidEditingException {
    final ITransactionManager transactionManager = projectAccessor.getTransactionManager();
    IUnsafeControlAction uca = null;
    try {
        transactionManager.beginTransaction();
        IModelEditorFactory modelEditorFactory =  AstahAPI.getAstahAPI().getProjectAccessor().getModelEditorFactory();
        StampDiagramEditor stampDiagramEditor = modelEditorFactory.getModelEditor(StampDiagramEditor.class);
        IControlStructureDiagram controlStructureDiagram = stampDiagramEditor.createControlStructureDiagram(analysis, "controlStructureDiagram");

        StampModelEditor stampModelEditor = modelEditorFactory.getModelEditor(StampModelEditor.class);
        IComponent component1 = stampModelEditor.createComponent(analysis, "component1");
        IComponent component2 = stampModelEditor.createComponent(analysis, "component2");
        IControlLink controlLink = stampModelEditor.createControlLink(component1, component2);
        IControlAction controlAction = stampModelEditor.createControlAction(controlLink, "controlAction");
        INodePresentation component1Presentation = stampDiagramEditor.createNodePresentation(component1, createPoint2D(100.0, 100.0));
        INodePresentation component2Presentation = stampDiagramEditor.createNodePresentation(component2, createPoint2D(250.0, 250.0));
        ILinkPresentation controlLinkPresentation = stampDiagramEditor.createLinkPresentation(controlLink, component1Presentation, component2Presentation);

        IUCATable ucaTable = stampDiagramEditor.createOrGetUCATable(controlStructureDiagram, "ucaTable");
        INamedElement guideword0 = analysis.getUCAGuideWords().get(0);
        uca = stampModelEditor.createUnsafeControlAction(controlAction, guideword0, "UCA1");
        uca.setIdentifier("UCA1-N-1");
        transactionManager.endTransaction();

        transactionManager.beginTransaction();
        ucaTable.setCell(controlAction, guideword0, Collections.singletonList(uca));
        transactionManager.endTransaction();
    } catch (BadTransactionException e) {
        transactionManager.abortTransaction();
    }
    return uca;
}

private Point2D createPoint2D(double x, double y) {
    Point2D location = new Point2D.Double();
     location.setLocation(x, y);
     return location;
}

Edit Diagrams and Presentations

Get StampDiagramEditor

You will use StampDiagramEditor to create, edit and delete diagram, table and presentations.

    ProjectAccessor projectAccessor = AstahAPI.getAstahAPI().getProjectAccessor();
    IDiagramEditorFactory diagramEditorFactory = projectAccessor.getDiagramEditorFactory();
    StampDiagramEditor diagramEditor = diagramEditorFactory.getDiagramEditor(StampDiagramEditor.class);

Create Control Loop Diagram

// Transaction processing is required
public IControlLoopDiagram createControlLoopDiagram(ILinkPresentation controlLinkPresentation)
throws ClassNotFoundException, InvalidUsingException, InvalidEditingException {
    ProjectAccessor projectAccessor = AstahAPI.getAstahAPI().getProjectAccessor();
    IDiagramEditorFactory diagramEditorFactory = projectAccessor.getDiagramEditorFactory();
    StampDiagramEditor diagramEditor = diagramEditorFactory.getDiagramEditor(StampDiagramEditor.class);
    IControlLoopDiagram diagram = diagramEditor.createControlLoopDiagram(controlLinkPresentation, "test");
    return diagram;
}

Create nested component presentation

// Transaction processing is required
public INodePresentation createNestedNodePresentation(StampDiagramEditor editor, IComponent parent, IComponent child,
            Point2D location) throws InvalidEditingException {
    INodePresentation parentNodePresentation = createNodePresentation(editor, parent, location);
    return editor.createNodePresentation(child, parentNodePresentation,  location);
}

// Transaction processing is required
public INodePresentation createNodePresentation(StampDiagramEditor editor, IComponent model,
            Point2D location) throws InvalidEditingException {
    return editor.createNodePresentation(model, location);
}

Create Loss Scenario Table

// Transaction processing is required
public ILossScenarioTable createLossScenarioTable(IUnsafeControlAction uca)
        throws ClassNotFoundException, InvalidUsingException, InvalidEditingException {
    ProjectAccessor projectAccessor = AstahAPI.getAstahAPI().getProjectAccessor();
    IDiagramEditorFactory diagramEditorFactory = projectAccessor.getDiagramEditorFactory();
    StampDiagramEditor diagramEditor = diagramEditorFactory.getDiagramEditor(StampDiagramEditor.class);
    ILossScenarioTable table = diagramEditor.createOrGetLossScenarioTable(uca, "lossScenarioTable");
    return table;
}

Delete Tables

// Transaction processing is required
public void deleteUCATable(IUnsafeControlAction uca, IControlStructureDiagram controlStructureDiagram)
        throws ClassNotFoundException, InvalidUsingException, InvalidEditingException {
    ProjectAccessor projectAccessor = AstahAPI.getAstahAPI().getProjectAccessor();
    IDiagramEditorFactory diagramEditorFactory = projectAccessor.getDiagramEditorFactory();
    StampDiagramEditor diagramEditor = diagramEditorFactory.getDiagramEditor(StampDiagramEditor.class);
    IUCATable ucatable = diagramEditor.createOrGetUCATable(controlStructureDiagram, "ucaTable0");
    if (ucatable != null) {
        diagramEditor.delete(ucatable);
    }
}

Supported model / Presentation list

See Astah STAMP/STPA API Structure details: STAMP/STPA Overview in Javadoc

Supported Models in Each Diagram

Summary of supported models of each STAMP/STPA diagram. See model details:StampModelEditor.
See diagram details:StampDiagramEditor.

Diagram Class Related Model Structure Get models Create models
Control Loop Diagram IControlLoopDiagram Control Loop Diagram ✓ ✓
Control Structure Diagram IControlStructureDiagram Control Structure Diagram ✓ ✓
PreconditionTable IPreconditionTable PreconditionTable ✓ ✓
AccidentHazardSafetyConstraintTable IAccidentHazardSafetyConstraintTable AccidentHazardSafetyConstraintTable ✓ ✓
UCATable IUCATable UCATable ✓ ✓
LossScenarioTable ILossScenarioTable LossScenarioTable ✓ ✓
CountermeasureTable ICountermeasureTable CountermeasureTable ✓ ✓

Supported Presentations in Each Diagram

This is a list of Presentation in Astah. To find out which presentation is editable or not, please refer to the StampDiagramEditor.

Diagram Class DiagramEditor INodePresentation ILinkPresentation
Control Loop Diagram IControlLoopDiagram StampDiagramEditor ✓ ✓
Control Structure Diagram IControlStructureDiagram StampDiagramEditor ✓ ✓