Code documentation

Features

• Plugin specific files

• the plugin needs to store different kinds of files: configuration files, survey results, recorded events, program snapshots, etc

• because of the nature of how IJ and Eclipse run, there are multiple paths where the plugin stores its files. When you open a project in IJ or a workspace in Eclipse, both IJ and Eclipse spawn a new instance of the IDE over that project / workspace. This means that both IDEs have two kinds of locations: the installation location of the IDE (where the IDE stores information relevant to all IDE instances, like common settings for all plugins) and the instance location (where the IDE stores information relevant only to a specific instance). This means that in both Eclipse and IJ plugins have two storage spaces. Thus, our plugin also has two storage paths: the local storage (specific to each project / workspace) and the bundle storage (common to all IDE instances). There is one bundle storage, and multiple local storages.

  • the local storage: eventFiles, workspace properties ("config"), logs, project snapshots, projects to ignore, known projects
  • the bundle storage: install properties ("config-install") that are global to all instances (e.g., uninstall date, FTP settings), survey responses, participant

• since our plugin supports updates, and since the event format may change from update to update, we store version sensitive files in versioned files

• StorageManager knows how to provide the local and bundle storage, and versioned variants

• File syncing between the local storage and the bundle storage

• the user may perform activities that lead to the deletion of the plugin's files (upgrading the IDE leads to the deletion of the bundle storage, deleting or creating new projects or workspaces leads to new local storage). When this happens we do not want to redo certain tasks, like running the survey or resetting the uninstall date. To prevent this, we backup the bundle storage in all the local storages.

• we also use the backup mechanism to detect new installations (when the bundle storage files do not exist anywhere) and perform installation specific tasks (e.g., running the survey).

• the policy for backup is implemented in Installer and InstallerOperation

• Uninstall

• plugin must stop recording after a certain amount of time

• Uninstaller is responsible for knowing when the plugin should shut down. The uninstall date is set at plugin installation

• Snapshots

• we need to snapshot the entire project on certain key moments:

  • Eclipse:
    • recording an event in a previously unrecorded project
    • when the IDE is closed
    • when plugin is updated
  • IJ:
    • when the plugin is first started
    • when the IDE is closed
    • when the plugin is update

• snapshotting is useful for:

  • it allows us to build the entire recorded project after any change
  • if there is a recording error that would cause spurious replay, snapshotting at regular intervals reduces the section length of bad recordings

• Event recording

• overall picture

• recorded events

• decoupling event format, storage format, and server storage

• Plugin update

• Choose which projects to record

Important Code entities

• Entry methods (main methods)

• These are methods where the control flow of the plugin starts. It's good to read them to get a sense of how all the supported use cases are instantiated. Reading both Eclipse and IJ entry methods gives you a good sense of the common concepts

• IntelliJ: recording is performed on a per project basis (an opened instance of IJ has only one project)

  • entry point: COPEComponent.projectOpened()

• Eclipse: recording is performed on a per workspace basis (an opened instance of Eclipse has multiple projects)

  • entry point: COPEPlugin.start() which then calls StartPluginUIJob.runInUIThread()

• IDE agnostic interfaces

• These interface (and abstract classes) reside in the common infrastructure repository and define common functionalities for both IDEs. Both IDEs implement these interfaces.

• StorageManager: provides the IDE specific paths to the local storage, the bundle storage, and to the versioned variants of these paths (see section on plugin stored files).

• Installer

  • InstallerHelper
  • InstallerOperation
  • SurveyOperation

• RecorderFacade