SeSAm Spring Symposium SeSAm Developers Tutorial Rainer Herrler, University of Würzburg

1. SeSAm Spring Symposium SeSAm Developers Tutorial Rainer Herrler, University of Würzburg

2. Prerequisites and aims of this tutorial Steps to load SeSAm into your Workspace General things about plugins Classification of Plugins Integration of Plugins Examples of Plugin Development Example 1: Primitive ATan2 Example 2: Type 3Dimensional Point Example 3: Focus Feature Example 4: Simple entry in the Menubar Example 5: The Focus Finder Example 6: Panel for FocusFeature Tipps and Tricks Overview

3. We presume you have: Modeling experience in SeSAm JAVA-Knowledge Afterwards you should have: Knowledge about important Interfaces Competence to develop plugins Ability to program addional features Prerequisites and aims of the Developer-Tutorial

4. Getting SeSAm into your workspace • Start Eclipse • Free Java-IDE (www.eclipse-org) • Other Java-IDE‘s are also possible but the description below has to be adapted • Install „CVS SSL Plugin“ (http://home.arcor.de/rolf_wilms/) • Select „File – Import – Team Project Set“ and open „sesam.psf“ • Ask for lastest „sesam.psf“ • It contains a description about the basic CVS-Server-data the required projects • Enter your user-name and password • We will create a repository account on request • Afterwards the necessary projects are gooing to be downloaded automatically. • Run SeSAm • SeSAm Application/de.uniwue.ki.gui.mas.application.SeSAm.java

5. SeSAm Project Dependencies User Interface Layer Kernel Utilities Layer

6. Kinds of Plugins and Examples • Additíonal Primitive • New Data Type • Feature Plugin • Menu Entries • Declaration Panels • Context-Menue

7. Kinds of Plugins and Examples • Definition: • Defines new Functions or Actions for an Agent • Existing Examples: • GetFirst(Iterator<T>) • Print(String) • Typical indicators for application: • Appclicable function/action by all agents • Independent of the agents state • Very generic time-consuming User Function • New thinkable example: • Mathematical Function „atan“ • …. • Additíonal Primitive • New Data Type • Feature Plugin • Menu Entries • Declaration Panels • Context-Menue

8. Additíonal Primitive New Data Type Feature Plugin Menu Entries Declaration Panels Context-Menue Kinds of Plugins and Examples • Definition: • Defines new data types • Existing Examples: • Specific Types (Boolean, String, Image,..) • Generic Types (List, Number,..) • Typical indicators for application: • Data type is needed by hardcoded primitives • Data type cannot be represented by any primitive type • New thinkable examples: • 3dimensional Position • DataBaseConnection

9. Kinds of Plugins and Examples • Definition: • Defines a new feature for an agent • Features provide states and functions for agent • Existing Examples: • Spatial Info, Evolution • Database Feature • Typical indicators for application: • Functions are dependent of the agents state • Feature cannot be realized by a user feature • New thinkable example: • 3-dimensional spatial info • …. • Additíonal Primitive • New Data Type • Feature Plugin • Menu Entries • Declaration Panels • Context-Menue

10. Kinds of Plugins and Examples • Definition: • Defines an entry in the plugins menu • An action can be assigned to the entry • opening a window • changing the model • Existing Examples: • Model print (html) • Protegé • Typical indicators for application: • Export and Import purposes • Configuration of Features • New thinkable example: • Java Code Generation from the model • Additíonal Primitive • New Data Type • Feature Plugin • Menu Entries • Declaration Panels • Context-Menue

11. Kinds of Plugins and Examples • Definition: • Specialized panels for certain types of declarations • Existing Examples: • Spatial Info • Spatial Map • Typical indicators for application: • A feature class needs to be configured • New thinkable examples: • Scheduling feature showing a time table • …. • Additíonal Primitive • New Data Type • Feature Plugin • Menu Entries • Declaration Panels • Context-Menue

12. Kinds of Plugins and Examples • Definition: • Context Actions on certain declarations • Existing Examples: • Find References • Inline Method • Typical indicators for application: • Refactorings • … • New thinkable examples: • Extract Superclass (for User Types) • Move User Function to Feature… • Additíonal Primitive • New Data Type • Feature Plugin • Menu Entries • Declaration Panels • Context-Menue

13. …to a SeSAm Installation (Deployment) Create a plugin.ini Bundle plugin.ini and needed .class-files to a single jar Put it to ../SeSAm/pulgins Start SeSAm …when running SeSAm from eclipse (Development) Create plugin.ini Put it to ../SeSAm Application/plugins/ Extend Classpath of Run-Configuration with plugin projects How to add Plugins…

14. Where do I find the „ini“-Files in eclipse • Locations • Active Ini-Files are stored in „plugins“ • Inactive Ini-Files are stored in „pluginsOff“ • To add a plugin do the following: • create „plugins“ • move your desired plugins

15. <plugin> <featureSection> <feature className="de.uniwue.ki.mas.basics.feature.spatial.SpatialMapFeatureClassDeclaration" singletonMethodName="getInstance"/> <feature className="de.uniwue.ki.mas.basics.feature.spatial.SpatialInfoFeatureClassDeclaration" singletonMethodName="getInstance"/> </featureSection> <objectActionSection> <objectAction className="de.uniwue.ki.gui.mas.basics.feature.spatial.SpatialMapObjectFeatureInstDeclPanelActionFactory"/> <objectAction className="de.uniwue.ki.gui.mas.basics.feature.spatial.SpatialMapObjectFeaturePanelAndActionFactory"/> <objectAction className="de.uniwue.ki.gui.mas.basics.feature.spatial.WriteableHasSpatialInfoDeclPanelActionFactory"/> </objectActionSection> <typeSection> <type className="de.uniwue.ki.mas.basics.feature.spatial.SpatialInfoType" singletonMethodName="getInstance" variableType="true" argumentDeclarationEditorClass="de.uniwue.ki.gui.mas.basics.feature.spatial.SpatialInfoTypeArgumentEditorPanel"/> <type className="de.uniwue.ki.mas.basics.feature.spatial.position.Position2DType" singletonMethodName="getInstance" variableType="true" argumentDeclarationEditorClass="de.uniwue.ki.gui.mas.basics.feature.spatial.Position2DArgumentDeclarationEditor"/> </typeSection> </plugin> Example „spatialPlugin.ini“-File

16. The found plugins are loaded at startup…

17. Example One: Programming Mathematical Functions Suppose we want to add a new primitive “atan2” with arguments x and y, that is defined like this:

18. Create the Function Describes effects of the function (semantics) Important at runtime Function must implement IFunction Create a FunctionDeclaration Describes input and output of a function (syntax) Important at modelling time FunctionDeclaration must implemet IFunctionDeclaration Stategy for beginners: Look for a similar Function (same or similar output and input parameters) Copy and modify this FunctionDeclaration and Function Steps to realize this function

19. Choose abstract superclass for Function Atan2 • Choose superclass accoring to the return value • void AbstractFunctionAction • boolean AbstractBooleanFunction • int AbstractIntegerFunction • double AbstractDoubleFunction • Otherwise choose • AbstractFunction - If the return value is definitly not one of the above • AbstractFunctionDynamic – If the return value might be one of the above, but it is uncertain which one

20. Creating the Function

21. What happens when? constructor is called when simulation run is created(compilation from the model declarations) execute() is called at runtime Notify that there might be constant Functions RandomInteger(1,10) is not constant +(10,20) is constant +(10,GetVariable(myVar)) is not constant What are ExecuteFunctionArgs ? Contain a reference to the world Reference to the active agent Backgroundknowledge about Function

22. SetVariable DoWith + Not Append Or Choose abstract superclass for FunctionsDeclaration Atan2 - Examples

23. Choose abstract superclass for FunctionsDeclaration Atan2 - Rules • Classify your FunctionDeclaration • specific if all output and input parameters are specified • generic if at least one output- or input- parameter has to be specified by the modeler • If „specific“ classify subtype • Args if a fixed number of input types can be given • UnlimitedArgs if any number of input parameters of one specific type can be given

24. FunctionDeclaration Atan2

25. FunctionDeclaration Atan2 • We still have compile-errors because we haven’t implemented the abstract function createFunction(..)

26. Create „Atan2Plugin.ini“

27. Add plugin projects to the classpath

28. And now we have the new function available

29. Example Two: Three-dimensional position and functions • And now we want to • Create a new type with a plugin • Create functions for this type • Steps • Defining a class to represent the types value • Declaring an according SeSAm Type (ISpecificType) • Defining two functions operating on that type.

30. Defining the representing class for a threedimensional point

31. List<T> Number Position2D String Choose abstract superclass for Type Position3D

32. Declaring a SeSAm type

33. Creating 3DPlugin.ini

34. Type is known in SeSAm but at the moment: values cannot be created, and no existing function could deal with the values. Two possibilities for creation: Defining argument editors Defining constructor primitives Signatures of possible primitives: Position3D CreatePosition3D(IntegerType x, IntegerType y, IntegerType z) DoubleType Distance3D(Position3D pos1, Position3D pos2) Creating functions is analogous to Example 1 Next step would be … defining Functions and FunctionDeclarations

35. Example 3. Programming a SeSAm builtin Feature • Focus-Feature Description • Select one single SimObject (Ressource or Agent) as target • Referencing the target and retargeting shall be possible • Provided Methods • SimObject GetFocusObject() • Void FocusObject(SimObject) • Provided Variables • No Variables used in this example • Internal State • Stores a SimObject • Is not accessible from outside

36. FeatureClassDeclaration 1 n AgentClassDeclaration ObjectFeatureClassDeclaration 1 1 n n AgentInstanceDeclaration ObjectFeatureInstanceClassDecl. 1 1 n n Agent (at Runtime) ObjectFeature FeatureDeclarations according to the different levels of agent declarations

37. FeatureDeclaration..

38. ObjectFeature.. holds the state at runtime

39. Example Feature Function… • Analogous you can create the action SetFocusedObject(SimObject)

40. FocusPlugin.ini and the effect

41. Example 4: New simple menu-entry

42. Watching the effect

43. And now we want to Create derive information from the model Find and show all agents equipped with the focus feature Steps Defining a menu entry Searching in the model representation Opening a window Example 5: FocusFinder

44. The root of the model representation

45. Similarities to the model tree help understanding the structure….

46. FocusFinder code….

47. And now we want to Show the Featues state at runtime Add a new GUI-Element to SeSAm Steps Defining a Renderer Panel for the FocusObjectFeature Defining a IObjectPanelFactory to generate the Renderer Panel Wrapping this into a IObjectPanelActionFactory Example 6: Focus Panel at Runtime

48. Step 1. Defining a Renderer Panel

49. Step 2. Defining the Panel Factory

50. Wrapping PanelFactory in PanelActionFactory