COM3205 LoDChecker Eclipse Plugin Project Paul Freeman December 5, 2002 INSTALLATION: To use this Eclipse plugin, place the entire unzipped plugin folder "edu.neu.ccs.LoDChecker_1.0" into the Eclipse plugin directory. Shutdown Eclipse if necessary and then start the Eclipse environment. REQUIREMENTS: Code in the LoDChecker itself requires: java 2 SDK 1.4 or higher to be installed. Failure to have this library installed and on the classpath of the developing project which is checker enabled will cause a compile time error to occur in the checker code. The plugin requires the following plugin versions (or higher) to be installed: org.aspectj.ajde_1.0.6 org.eclipse.ajdt.ui_0.5.2 org.eclipse.core.resources org.eclipse.ui org.eclipse.jdt.core org.eclipse.swt org.eclipse.debug.core org.eclipse.jdt.launching note: If any of these plugins are missing, the LoDCheckerPlugin will be disabled when Eclipse starts. USE: To use this plugin, and fine tune the checking it provides, access the checking options through the LoDChecker property page that is associated with all Java projects. The property page can be accessed by selecting the project in the Package Explorer, then selecting the File->Properties menu from the toolbar. Once you have the propety page displayed, you can choose between either a Class Form checker or an Object Form checker. You can also fine tune either checker through numerous check boxes offering predefined choices. The advanced user may also enter custom join points to fine tune the checker even further. Currently there is no support to ensure you have followed valid AspectJ syntax when entering custom join points. Errors in syntax will cause errors during the build process. Once you have enabled the checker, you will need to rebuild the project to be checked before the LoDChecker will truly be activated on this project. A violations display will be opened when a project is enabled with the LoDChecker. This display will be populated with all of the violations for the currently selected project only after a project that is "checker enabled" is run. All Law of Demeter violation checking is currently done at runtime. Therefore changes made to violating code after will not be correctly reflected in the violations display until the project is recompiled and rerun. Also, all violations in a particular project may not be found during one program execution as the checker depends on code execution to detect violations. Code that violates the Law of Demeter, but is not actually executed, will not be flagged as a violation of the Law of Demeter. Double clicking a violation in the display will open the file that contains the display and highlight the line where the violation occurrs. If for any reason, more than one file with the same name exists in the user's source directory then a view will not be opened since it is impossible to determine exactly which file the violation came from. The violations display will also display the statistics for a specific program execution on a separate "statistics" tab within the display. There are two options that correspond to the violations display: - There is a toggle button to switch between displaying or not displaying violations specific to the currently executing object "this" and the "target" object/class of the violation. - There is also an option to report violations in a "light" or "normal" mode. The light mode displays violations only when a program finishes executing and the normal mode displays violations as a program is executing. Currently only the light mode works therefore the view is forced to remain in the light mode. DESIGN: The plugin comes with two additional libraries: log4j-1.2.7.jar aspectjrt.jar The AspectJ runtime library was included with this package to ensure that the LoDChecker would know it's location. This library is also included with the AspectJ plugins, but including it ourselves ensures compatibility with future AspectJ plugins that may move it's location, or not include it. The log4J library is included as it is used to create a log file of violations by the LoDChecker version enabled for the project being checked Both libraries will automatically be included in the classpath of the project being built with the LoDChecker. There is no need to add them manually. A log configuration file that allows for tuning of the log files produced, is also automatically generated and placed in the project's directory. Although tuning this file may adversly effect the ability of the plugin to display violations. The checker will not overwrite changes to the configuration file, but if the configuration file is deleted for any reason, it will be regenerated prior to the "running" of a project. The java files for the Checker itself are hidden from user view. They are copied to a location reserved for our plugin and the specific project being worked upon. This location is in the .metadata directory of the active workspace. This location is convenient for a couple of reasons: 1. the location is unique for every project in the workspace - allowing for easy inclusion of custom LoDChecker files to be used with a specific project. 2. the files in this location are automatically deleted when the project is deleted. Only three files are placed directly in the user's directory: 1. the log configuration file that provides fine tuning of the log of violations that will be produced 2. the log file that is generated after a run of the user's program by the LoDChecker form selected for the currently executing project. 3. a custom AspectJ build configuration file (*.lst) that includes source files of the checker form selected. The custom *.lst file is regenerated prior to every build. It will always rewrite itself to ensure it includes all of the files in the version of the checker currently selected. There is no need to select this file prior to a build of the user's program. In fact the current design hides the generated list file from the view of the user. The user is allowed to select any build file they choose. Prior to a build, our plugin examines the currently selected build file and rewrites the custom LoDChecker build file by combining the selected build file with the files required by the checker version that is currently selected. The Builder.java file can be examined to see how this is accomplished. The Builder class itself is added to the list of builders for a project when a project is given the LoDChecker nature (see LoDCheckerProjectNature.java). The Builder class itself executes just prior to a build of a given project in the Eclipse environment. When the builder is added to a project, it is placed just before the AspectJ Builder, ensuring that we will be able to modify the list file currently associated with the project being built. The order of builders associated with a project is maintained by the Eclipse environment between shutting down and starting up of the Eclipse environment. All project specific LoDChecker selections are also maintained between Eclipse sessions through an API that specifically allows for storing project specific variables. The View is designed to display violations and statistics from the last run of the currently selected project. To do this, the logfile which is being written to is monitored during execution of a running project for changes made to it by the LoDChecker. Any changes which are made to this file are read in and rewritten to a file hidden from the users view. It is placed in the project-checker specific location reserved in the .metadata directory of the workspace. Hiding the latest violations here helps to ensure that they will not be erased by the user. Also, this file only stores the latest violations. The violations file which was monitored, stores all violations from all sessions. However, the monitored violations file may also be reset during a program execution once it reaches a size limit. If so, then it may not contain all of the violations from a specific program execution. Therefore the user may be mislead if the view does not display all violations that occurr in a specific program execution. Since violations are reported only by file name where they occurr, it is impossible to determine the file of a violation if more than one file with the same name exists in the workspace. Therefore, if that situation arrises, double clicking to open a file causes an error message to be displayed stating that the file where the violation occurred cannot be displayed due to a name conflict. KNOWN ISSUES: 1. Currently, (since Eclipse will not load a plugin until the first bit of code from a plugin is required) to make the plugin function correctly, you must activate it at least once by viewing the property page. Or displaying the view associated with the checker. If you do not do this prior to the build of a LoDChecker enabled project, an error will occur in the AspectJ plugin. This error occurs because the AspectJ plugin has not been properly loaded prior to a build attempt with the plugin. I suspect that if AspectJ views are visible, this error will not occurr. If this error does occur, it will deactivate both the AspectJ and LoDChecker plugins. Eclipse will need to be shut down and restarted before they will work again. I have attempted to fix this error by adding encorporating the "earlyStartup" extension point into the plugin. However, this did not work as desired because the AspectJ plugin (during it's construction) relies on a function which returns null at the time of "earlyStartup": PlatformUI.getWorkbench().getActiveWorkbenchWindow(); There is no active workbench window at the time of early startup. I attempted to work around this fact by adding a window listener to the workbench at early startup. When the first window then opens or activates, the AspectJ plugin would then be loaded. However, there is no "windowOpened" event thrown to the window listener when it is registered at earlyStartup !? This would seem to be a bug in the Eclipse environment.