JNI Eclipse Development Interface (Jedi) An Eclipse Plug-In for JNI …faculty.salisbury.edu/.../EclipseJNIDevInterface-2010.pdf · 2012. 4. 25. · JNI Eclipse Development Interface

JNI Eclipse Development Interface (Jedi)

An Eclipse Plug-In for JNI Development

University of Illinois at Urbana-Champaign

CS 428 : Software Engineering IIProf. Darko Marinov

Spring 2010

Author:JNI Group

Milestone Supervisor:Charlie Meyer

CONTENTS i

Contents

1 Project Description 11.1 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Team . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.3 Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.4 Other Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2 Development Process 32.1 Iterative Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.2 Refactoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.3 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.4 Collaborative Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3 Requirements & Specifications 53.1 Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53.2 AST Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.3 Javah Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.4 C Code Emitter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83.5 Refactoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83.6 Content Assist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4 Architecture & Design 104.1 Eclipse framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104.2 Jedi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4.2.1 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104.2.2 Metaphor(s) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.2.3 Design Influences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4.3 Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.3.1 Issues and Tips: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

4.4 AST Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144.5 C Code Emitter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.6 Refactoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4.6.1 Issues and Workarounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184.7 Content Assist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

5 Future Plans 195.1 Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195.2 Functionality Ideas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

5.2.1 Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195.2.2 C Code Emitter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195.2.3 Refactoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195.2.4 Content Assist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

5.3 Member Reflections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

6 Appendix 226.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226.2 Running the plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226.3 Running the tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

6.3.1 Automated AST Handler tests . . . . . . . . . . . . . . . . . . . . . . . . . . . 226.3.2 Automated Emitter tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226.3.3 Manual Content Assist tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

CONTENTS ii

6.3.4 Manual Refactoring tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236.4 Automated GUI tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

6.4.1 Quick Description of what is tested . . . . . . . . . . . . . . . . . . . . . . . . . 236.4.2 How to run the tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246.4.3 What to expect during the tests (visually) . . . . . . . . . . . . . . . . . . . . . 246.4.4 What results to expect from the tests . . . . . . . . . . . . . . . . . . . . . . . 24

6.5 Known Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256.5.1 Automated GUI tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256.5.2 Automated ASTHandler and Emitter tests . . . . . . . . . . . . . . . . . . . . 25

1 Project Description 1

1 Project Description

The Jedi is an Eclipse plug-in that provides support for auto-generation and refactoring of C codethat implements Java native interfaces via JNI.

1.1 Motivation

In order to extract input and environmental data from a Java program, it is usually necessary towrite special “glue” code at the beginning of each native function implementation specified using JNI.Similarly, this type of code is also usually needed at the end of each native function implementationin order to successfully return data and control back up to the calling Java program. These blocks ofcode are typically unintuitive and tedious to write, making JNI interfaces especially tough to code,requiring significant amount of time to ensure correctness, and setting the stage for a higher probabilityof errors being introduced in development. Therefore, the motivation behind Jedi is to simplify thetask of developing with JNI by provided automated mechanisms for creating and modifying the Csource code that implements Java native function declarations.

1.2 Team

Our group consisted of 6 members, each with prior experience in C and Java development. Noneof us had any prior experience developing an Eclipse plug-in, but we now all love developing Eclipseplug-ins and find it to be a calming experience, especially since it is so easy to find useful documen-tation.

The team consisted of the following members:

• Jon Kessler ([email protected])

• Matt Kirn ([email protected])

• Alex Loeb ([email protected])

• Yen Shine Low ([email protected])

• Ben Towal ([email protected])

• Tim Tsu ([email protected])

1.3 Terms

• JDT - Java Development Tools. This is the set of plug-ins that provide a Java developmentenvironment within Eclipse.

• CDT - C/C++ Development Tools. This is the set of plug-ins that provide a C/C++ develop-ment environment within Eclipse.

• JDK - Java Development Kit. This is a set of programs and API implementations that aid inJava development.

• javah - C header stub generator. This is a program included with JDK that generates C headerfiles with stub declarations of native methods for a given Java class.

• wizard - A term describing the mechanism that provides a series of GUI pages to a user forsimple graphical input in order to produce a wizard-specific result.

• AST - Abstract Syntax Tree. This term describes a data structure that represents the parsedelements of a particular code file.

1.4 Other Notes 2

• content assist - This term describes the mechanism that provides an in-editor menu to allow auser to auto-complete a line of code within a given context.

1.4 Other Notes

Familiarity is assumed with the following technologies and concepts:

• Eclipse Galileo (3.5)

• JUnit 4

• XP Development Process

• UML 2.0

• Object Oriented Architecture, Design, and Programming

2 Development Process 3

2 Development Process

We followed our own process, which incorporated many elements from XP including:

• Code Spikes

• Planning Game

• Simple Design

• System Metaphor

• Small Releases

• Pair Programming

• Refactoring

• Continuous Integration

• Sustainable Pace

• Coding Standards

2.1 Iterative Development

Our development occurred according to 2 week iterative milestones. At the start of each milestone,we would agree to the user stories to be accomplished. Oftentimes, the ideas for the user stories fora given iteration would arise during the previous iteration. As a result, we selected and refined userstories according to what we thought we would be able to accomplish within a given milestone. Therequirements for each user story were always immediately apparent, and sometimes we were even ableto split user stories into multiple user stories and the end of an iteration if there wasn’t enough timeto fully implement all requirements.

Once the user stories were selected, we began development. Development consisted mostly ofsearching for documentation and code examples for the Eclipse framework, and then progressiveimplementations of features as we better understood parts of the system.

After development, we would write tests for any code in stable condition. By the time tests werewritten, the milestone was wrapping up. At the end of a milestone, we would present the currentstate of our development and any working tests, and discuss any issues along with any thoughts toconsider for the next milestone. Finally, we would repeat this entire process for the next milestone.

2.2 Refactoring

We refactored several times during the course of development. Our refactorings occurred as codesmells became apparent, or when the development of a new feature required them. The nature ofdeveloping an Eclipse plug-in almost required us to refactor our code since we would oftentimes startimplementing a user story only to discover there is a cleaner way to do it using a specific Eclipse API.

Our refactorings were generally minor changes to specific parts of each component. However,during our fifth iteration we organized a code review of each component and, based upon its results,we subsequently refactored each component which required structural changes to the C Emitter andthe Wizard.

As one example of a structural refactoring, our wizard component was refactored during the fifthmilestone. The purpose of this refactoring was to move the task of handling the finish operationof the wizard to each page that had the ability to let the user finish. The refactoring was to, foreach finishable page of the wizard, implement a new interface that the wizard controller could invokewithout needing to know the page that clicked finish. This removed complexity from the wizardcontroller and allowed us to reuse code that was used by each finishable page of our wizard.

2.3 Testing 4

2.3 Testing

Testing occurred in each iteration of our project. The most testing was done manually in order toverify our understandings about some of the functionalities of Eclipse. In general, Eclipse is a quitecomplex system and therefore a lot of our development included mini proof-of-concepts in order toguide our implementations within the Eclipse framework.

We also developed automated tests after each component was in a sufficiently stable condition.The test-driven development paradigm of XP was not applicable from a practical standpoint, sinceoftentimes we had no idea what to test or our implementation could have changed drastically afterdiscovering more functionalities of the Eclipse framework. We generally had a small amount of auto-mated tests to present for each milestone, but once we discovered how to automate GUI tests towardsthe end of the project we quickly developed a suite of tests to cover almost every feature of our plug-in.Further automated tests for non-GUI components were developed towards the end of the project aswell.

2.4 Collaborative Development

We split our development into pairs of programmers, where each pair was responsible for a userstory or component of the system. Oftentimes, the requirements of the system would force us tocollaborate on the correct manner in which to implement a specific feature.

As one example of our collaboration, early in our development we had to agree on a common dataencapsulation model for our plug-in so that each component could use the data model independentlywithout worrying about the specific details of how each component would communicate with oneanother. As a result, we were able to provide an implementation for each component based upon theshared model and the data could simply be passed from one component to another.

Additionally, we would oftentimes share information with each other regarding how to do a specifictask within Eclipse. There were a few common Eclipse APIs that were used within each componentand so we would oftentimes ask one another how to use those APIs or just look at the implementingcode directly. Each pair regularly committed their code to our SVN repository and each member hadthe ability to examine the code of another component at any time. Each time we began to work, weupdated our entire project from version control to ensure that we were always working with the latestversion.

3 Requirements & Specifications 5

3 Requirements & Specifications

3.1 Wizard

The wizard component supports generation of JNI templates into C header and source files eitherby using an existing Java class or by creating a new one. The wizard is activated through the Eclipse“File → New → Other...” menu. Once the wizard is activated, the wizard expects the user to selectwhether to generate based off an existing file, or whether to create a new Java class.

If the user chooses to generate based upon an existing class, then the user must subsequently spec-ify the class to use. The class is specified using a GUI control to select a file in the active workspace.Once the class is specified, the user is allowed to click finish. The wizard currently does notallow the user to manually specify the file location. Additionally, no checks are madeto ensure that the class used is error-free or has native methods declared. The inputcontainer must be within a package.

If the user chooses to create a new class, then the user will be directed to a new page. On thispage, the user will be able to specify the output location of the generation, the name of the newclass, and any native method declarations to add to the new file. The wizard performs some checks toensure that the output container, class name, and native method signatures are valid. Once all fieldshave been specified and validated, the user is allowed to click finish. No checks are performed toensure that return/parameter types of method signatures are legal. Exceptions are notsupported. The output container must be within a package.

See Figures 1, 2, 3, and 4 for more details.

Figure 1: Wizard page to select the method of generation

3.1 Wizard 6

Figure 2: GUI control to select existing file

Figure 3: Wizard page to create new Java class with native methods

3.2 AST Handler 7

Figure 4: Dialog for adding a new native method declaration

3.2 AST Handler

The AST Handler component supports generation of native methods in a new or existing Javaclass given the definitions of those methods. The AST Handler accepts a native method signature asinput and generates as output a new Java class declaration with those native methods declared. Thewizard page that performs a JNI generation via a new class invokes the AST Handler.

The AST Handler assumes that the method definitions to generate would result in avalid Java class. This implies the following preconditions are met:

• No two methods have the same signatures

• Method names, argument names and type names conform to valid Java naming conventions

• The package that the class will be inserted into is an existing package

• The project that the class will be inserted into is an existing project

3.3 Javah Job

The javah job supports generation of a JNI C header file by invoking javah. The job accepts asinput the working directory from which to execute javah, the class path directory in which to searchfor class files, the output directory of where to store the generated header file, and the fully qualifiedclass name of the class to use for generation. The job outputs a JNI C header file in the outputdirectory specified. The javah job assumes that JDK is installed and that the classpathused to start Eclipse contains the directory of where javah is located.

3.4 C Code Emitter 8

3.4 C Code Emitter

The emitter supports generation of C source code for stub implementations of JNI C methodsdeclared in an existing header file. The emitter accepts as input the contents of a header file gener-ated by javah. The emitter generates as output the C source code to provide stub implementationsbased upon the return type and arguments of each method declaration in the header file. Therefore,the emitter is also able to parse the header file’s information. The emitter supports generation ofrudimentary “glue” code for primitive types, primitive array types, and String types.

3.5 Refactoring

The refactoring component supports refactoring of a Java native method declaration such that themethod signatures in the C source and header files are updated to reflect the changes. Refactoringis accomplished via a pop-up action which is activated from a right-click context menu inside of aneditor. The refactoring component supports simple refactorings such as return/argument type andmethod name changes. In particular, complex refactorings such as changing file names andoverloaded methods are not currently supported.

See Figures 5 and 6 for more details.

Figure 5: JNI refactoring context menu

3.6 Content Assist 9

Figure 6: JNI refactoring dialog

3.6 Content Assist

The content assist component allows a user to browse and select JNI API proposals when editingJNI C functions definitions in a C source file. When the user confirms a proposal selection, the codewill be inserted into the current line in the C file.

The content assist feature works as a pop-up menu when the user presses <Ctrl+Space> whileediting the C file, which presents a list of JNI API calls. When a particular proposal is selected,the API specification for that proposal is displayed. Currently, the content assist component isrudimentary and not context sensitive to the user’s edits, and only has proposals for JNIString and Array APIs. The content assist component assumes that CDT is installed.

See Figure 7 for more details.

Figure 7: JNI content assist proposals

4 Architecture & Design 10

4 Architecture & Design

4.1 Eclipse framework

Eclipse employs plug-ins in order to provide all of its functionality on top of (and including) itscore runtime system. This plug-in mechanism is light-weight and highly extensible.

Figure 8: Generic structure of Eclipse platform

4.2 Jedi

4.2.1 Architecture

Figure 9: Jedi package structuring

4.2 Jedi 11

Jedi is structured in a way that promotes maximal reuse of each component, whilst maintainingminimal levels of coupling among components. Each feature (wizard, refactoring, content assist) isseparated into its own package, and none of the features are dependent on any of the others.

The models package provides provides data encapsulation models of Java classes, methods, andarguments in order to reduce coupling between the wizard and AST Handler. These classes aresimple data classes with getters and setters, and the JNIMethod class has the ability to print methodsignatures to Strings.

The internal package provides services for externalizing strings. Essentially, this package storesthe properties files that holds all the strings used within the system along with the classes that providestatic access to these strings at runtime. The purpose of externalizing strings is to centralize the stringdefinitions in order to avoid duplicate strings, and also to provide the ability to change the stringswithout having to modify the classes that use those strings. The name “internal” was chosen tomaintain the convention of the Eclipse source code.

The com.sun.javadoc package stores some of the classes that the JDK uses to implement javah.These classes are used by the refactoring component to implement the task of mangling methodsignatures in order to conform to JNI conventions. Including these classes in the plug-in allows us toreuse trusted code. Additionally, the tools library from JDK is rather large, so rather than requiringit as a dependency, we instead just borrowed the relevant classes.

The rest of the features are described in detail below.

4.2.2 Metaphor(s)

The metaphor behind our system is effectively the aggregation of the metaphors of each of thethree features. The metaphor of the wizard captures the concept of a set of user interface controlsthat extract input from and provide visual feedback to a user. The metaphor of the content assistcaptures the concept of a menu dialog that assists a user in selecting code content to insert into atext file. The refactoring component is expressed through a pop-up action metaphor. This capturesthe concept of displaying a pop-up menu to the user in order to provide an option for refactoring.

Internally, the metaphors of emitter and AST capture the actions and interactions performed byeach component. The emitter captures the concept of emitting code according to a specific formatin a custom fashion. The AST package captures the interactions that the AST Handler has with theEclipse system in order to generate Java code.

4.2.3 Design Influences

Our design was significantly influenced by the Eclipse framework. Each of our components relieson Eclipse APIs to simplify several tasks. Some examples of such tasks include auto-generation Javacode, auto-building Java code, simplified mechanisms for executing external processes, and reusingpre-defined GUI controls and logic. Thus, our design was influenced in a way such that we structuredour components around the existing capabilities of the Eclipse architecture. In particular, each of thethree features, along with the AST Handler and the javah job, were designed around the API callsprovided by Eclipse.

The other frameworks used by Jedi include JUnit and SWT Bot. These were also very usefulduring development for providing simplified automated tests, and therefore the code for our tests wasinfluenced to a great extend by these frameworks. SWT Bot allowed us to implement several GUItests which we would have otherwise been unable to provide. However, SWT Bot is still an incubationproject and has some issues that restrict it from being able to test every GUI control. In particular,because of these issues, we were unable to provide automated GUI tests for the refactoring and contentassist components.

4.3 Wizard 12

4.3 Wizard

The wizard is provided via an extension point to the Eclipse new wizards menu. When the wizard isactivated, JediNewWizard is invoked by Eclipse to determine what pages to display to the user. Everywizard must implement an interface to specify the list of all potential pages that could be visited bythe user. Our wizard specifies JediGenerationChoicePage as the first page, and JediNewWizardPage

as a potential second page.In our wizard, we defined a new interface IFinishablePage that is implemented by each page of

our wizard. This interface allows the wizard controller to maintain a map of all pages that are finish-able (i.e. user can click finish). This is beneficial because, when a user clicks finish, Eclipse invokesthe wizard controller’s performFinish method. Since the wizard controller has each finishable pagestored, it can simply determine which page clicked finish and then invoke the performFinish methodwithin that page. This reduces the complexity of the wizard controller having to know how to handlefinishing for each possible page that can finish. Additionally, the interface allows each page to reusethe data it has stored internally, rather than having to expose its data via getter methods that thewizard controller would otherwise need to invoke.

The JediFinishHandler is responsible for handling the finish operations of each page. Since thefinish operations for each page share several tasks (compilation, javah invocation, C source emission),this results in substantial code reuse.

The rest of the classes in the wizard package define specific GUI controls used by JediNewWizagePage.The AddMethodDialog and JediChangeParametersControl reuse the code from the JDT refactoringengine for the GUI display.

See Figures 10, 11, and 12 for more details.

Figure 10: Class diagram of Eclipse wizard system

4.3 Wizard 13

Figure 11: GUI Outline of a wizard dialog page

Figure 12: Class diagram of Jedi Wizard

4.4 AST Handler 14

4.3.1 Issues and Tips:

There were a few minor issues with enabling the next/finish buttons at the appropriate times andrefreshing error states, but these are easily remedied by looking at available documentation. One tipabout GUI code is to always try to find an Eclipse GUI control to serve your purpose before youimplement one yourself.

4.4 AST Handler

The ASTHandler generates Java code by using JDT’s built-in Java AST modification APIs. Whenan ASTHandler is created for a given Java class, the Java document is loaded into memory and anAST object representing the underlying AST structure for that class is generated.

For a new Java class, a JNIClass object is passed into the addClassToFile(JNIClass) method.The AST object representing the file is modified based on the JNIClass object that was passed in bythe wizard. Then, the ASTHandler gets a TextEdit object that represents the changes in the Javafile corresponding to the changes made to the AST object. The changes are then applied to the sourcefile.

For an existing Java class, a JNIMethod object is passed into the addMethodToExistingClass(JNIMethod)method. The AST object representing the file is modified to add the method described by theJNIMethod object. In the same way described above, the ASTHandler generates the TextEdit objectrepresenting the changes in the Java file required to transform the source code of the file and appliesthose changes.

See Figures 13 and 14 for more details.

Figure 13: Class diagram of AST Handler

4.5 C Code Emitter 15

Figure 14: Sequence diagram of AST Handler

4.5 C Code Emitter

The Emitter component is divided up into two classes: The Emitter itself and the satellite CParserclass. The CParser class is responsible for extracting relevant information from the header file. TheEmitter class is then responsible for using that information to generate a C file as well as some usefulcode within each method. We decided that each method declaration and its corresponding return typewere the most useful information to extract because from these simple data chunks we can infer a lotof information about the file and can generate code to help the end-user. For instance, if we knowthe return type, we can generate code that declares a variable within the method of that type andreturns it at the end. We also generate special initialization code based on the variable types we haveinferred. Furthermore, we also aid the end-user by generating systematic names for the parametersof each method.

Originally we were continually rereading and reparsing the header file data each time we wantedto use it for any of these features. We refactored into the current design in order to simplify andoptimize this process by reading the data all at once and saving it in publicly accessible fields in theCParser.

The Emitter/CParser component is responsible for outputting this code once it has been written,via an OutputWriter object.

See Figure 15 for more details.

4.6 Refactoring 16

Figure 15: Sequence diagram of Emitter

4.6 Refactoring

The Alter Method Signature refactoring is implemented in the AlterMethodSignatureAction

class. When the context menu item for Alter JNI Method is clicked, the Eclipse system callsAlterMethodSignatureAction’s run() method. The IMethod under the current selection in the Javafile editor is retrieved and sent to the Change Signature refactoring engine. The refactoring engineautomatically displays a Change method signature dialog, validates the input from the user, andrefactors the Java method.

Upon successfully refactoring the JNI method on the Java side, the run() method gets the con-tents of both the .c and .h files. Then it performs a regex search for the original method signaturein mangled form in the corresponding C file strings and performs a text replacement with the newmangled method signature. Finally, the source and header file contents are set to the updated contentstrings.

See Figure 16 for more details.

4.6 Refactoring 17

Figure 16: Sequence diagram of Refactoring component

4.7 Content Assist 18

4.6.1 Issues and Workarounds

The CDT AST API does not allow modification of C AST structures. The workaround for this wasto use regex search and replacement on the raw text of the C source and header files.

4.7 Content Assist

The content assist works by first loading in the bundle of proposal templates and information whenthe proposals are referenced at runtime. Eclipse contains an NLS class which provides a template forcreating classes to load in message bundles for use in the content assist. The JediJNIString andJediJNIArray classes both extend NLS, and load in the bundles, which are stored in jniString.properties,and jniArray.properties respectively.

JNICompletionProposalComputer implements Eclipse’s ICompletionProposalComputer, and iscalled every time a content assist menu is invoked in CDT. The JNICompletionProposalComputer

wraps around the JNIProposalProcessor (which itself implements IContentAssistProcessor) andreturns a list of suggestions/proposals, encapsulated as a Proposal object.

See Figure 17 for more details.

Figure 17: Sequence diagram for content assist feature

5 Future Plans 19

5 Future Plans

5.1 Project

Our group currently has no plans to continue development on Jedi. However, anyone is free tocontinue development of the plug-in. The plug-in has been packaged into an update site locatedat http://cs.uiuc.edu/ kirn1, where you can install the plug-in into Eclipse directly or download thesource code.

5.2 Functionality Ideas

5.2.1 Wizard

• Add error-checking/validation to existing class generations

• Allow user to filter methods of an existing class to only generate a subset

• Allow user to specify non-native methods in a new class generation

• Add support for exceptions

• More validation of return/parameter types in new class generation

• Allow user to perform generation using default package

5.2.2 C Code Emitter

Support for more types, such as user-defined object arrays and full class instantiations. As theseare more involved types, requiring more detailed JNI code, we opted to implement the more primitivetypes first, but it would be useful to support other types as well.

5.2.3 Refactoring

• Support for overloaded method signatures.

• Support for refactoring class/file names.

• Support for user-defined C source and header locations.

5.2.4 Content Assist

Add context-sensitivity. This will require research on C statement regular expressions, as well asEclipse handling of it. Other improvements include adding more JNI functions, along with additionalproposal info for each one. To do so, a substantial amount of strings containing the proposals andinformation will have to be added into their respective properties bundle file. A refactoring of thecurrent design will have to take these into account, as it will be inefficient to store all of them withouta better formatting.

5.3 Member Reflections

• Jon Kessler

Our CS 428 project was a very interesting experience. Our group was able to produce an excellentplug-in for Eclipse after a great deal of hard work throughout the semester. I am truly glad to havebeen able to work on a good-sized project using a modern development methodology. Though theproject was difficult at times, due to the complexity of the Eclipse platform and to its lack of gooddocumentation, it was ultimately an excellent learning experience. Hopefully, our plug-in can even beuseful at some point to someone programming JNI code in Eclipse.

5.3 Member Reflections 20

• Matt Kirn

The project was initially my idea, and as such I am inclined to think it is/was a good idea and Iam pretty amazed at the level of progress we have made. Although some members might not havehad any interest in JNI specifically, I would hope that the true software engineering experience hasproved to be beneficial. Eclipse can definitely seem unintuitive and under-documented sometimes,but I would argue that it is much more documented than any system any one of us will come acrossin our professional lives. I can personally attest to working on much larger projects than Eclipse thatwere even more poorly documented, and even worse, there was no community of individuals to whomyou could ask questions or ability to search for code examples on the Internet. I personally thinkEclipse is a great example of a technically advanced architecture and serves as a great learning toolto experiment with. The fact that it is open source will only continue to drive more tools integrationand Eclipse will always continue to grow, which I think will put it on top in the long run as thereis always tech support and if you have any critical issues, you can always change the code yourself.Anyways, I enjoyed the project and the experiences with the team and milestones, and I hope thatour plug-in will serve as another useful tool in the ever-growing Eclipse framework.

• Alex Loeb

This project was the culmination of everything I learned throughout CS 427 and CS 428. Whilesome of the skills were forced through homework and milestone requirements, a great number of themproved to be intrinsically valuable to our team as we progressed through each milestone. The biggestchallenge I had, and I believe this is true for the rest of the group as well, was researching the EclipseAPI and scouring forums to find sufficient knowledge such that we could implement the features weneeded. In particular, it was often the case that we would implement a feature during one milestoneonly to turn around the next milestone and re-implement it utilizing a more appropriate mechanismwithin Eclipse. As a result of this iterative process, the value in writing good, clean code and usefulcomments became more and more apparent. If it had not been so challenging to write useful GUItests from the beginning, I believe we would have also found great value in a solid test suite. Overall,the entire project was instance after instance of refactoring and retooling our code base to make itconform to the existing standards within Eclipse. This is probably one of the most beneficial aspectsof the project in that we were exposed to useful practices and good habits not typically seen withinan academic setting. As our project stands as of the final submission, I am quite proud of what wemanaged to accomplish over the semester given that almost every member of our group had no priorexperience working with Eclipse APIs or Eclipse plugins.

• Yen Shine Low

Looking back, I think that from this project, it would be a lie for me to claim that I have learntanything technical or particularly new about Java, nor have I appreciated any of Eclipse’s beauty. Idefinitely do not want to develop another plug-in for it, nor do I fancy maintaining the project in thefuture.

Instead, the thing that I got most out of this would be experience in building a product fromscratch in a large group. It was definitely an eye opener, considering that this is my first time doingso. Along the way, I have also experienced some of the development issues/risks mentioned in class,specifically loss of interest on my part.

If there was anything I wish I have known going into the project, or at the beginning of thesemester, would have wished to know that this project would involve far too much head wrappingaround Eclipse details, and calling preexisting API and less on actually building something fromscratch. For instance, it took me around 6 hours looking up on and experimenting on how to get thecontent assist to display additional information, and when I finally know how that is done, it took atmost 2 hours only to add it into the plug-in.

For lack of a better word, I feel that this project is not intellectually challenging, and not fun atall. Regardless, I definitely learnt a lot of things from working on this, and it was a pleasure working

5.3 Member Reflections 21

in a team where every member is responsible. I am proud of my group mates, and appreciate all thatthey have done.

• Ben Towal - < no reflection provided >

• Tim Tsu

Working with the Eclipse Platform had both its positives and negatives. The Eclipse Platform hasa steep learning curve and it took a long time to sift through documentation, experiment with code,and reverse engineer existing plug-in code to learn how to do anything. As a result, I learned whatmethods worked better than others for finding out how to write an Eclipse plug-in. For example,locating existing plug-in code that performs a similar action is often more helpful than reading thedocumentation for the components in the API, if that documentation exists.

For the most part, developing a plug-in for Eclipse proved to be a difficult and frustrating expe-rience. In addition to the lack of useful tutorials for using many of the components in the EclipsePlatform API as well as the other plug-ins that we depended on, some functions that we expected tobe simple turned out to be complicated or nonexistent. As a result, our team had to be very incre-mental and flexible with the development of our plug-in. We often had to completely redesign certaincomponents after discovering that certain APIs did not work as we had expected. For example, wediscovered that the CDT AST parsing did not allow modification of the AST structure as the JDTAST parsing API allows.

Given these obstacles, I am very satisfied with the amount of progress that we made as a team.As a group we had no prior experience with Eclipse plug-ins and few of us had experience with JNIbefore working on the project. However, we successfully implemented several useful features for JNIdevelopment in the Eclipse platform. At the same time, there is still a lot of work that can be doneto improve upon the JEDI plug-in, including a custom JNI programming perspective, support forrefactoring all method types, and custom JNI build configurations.

6 Appendix 22

6 Appendix

6.1 Installation

You can install the Jedi via the update site located at http://cs.uiuc.edu/ kirn1. Follow thestandard procedure for installing an Ecipse plug-in. The Eclipse update manager should install anymissing required dependencies. Alternatively, if you wish to have access to the tests, you can downloadthe project from our SVN repository at https://csil-projects.cs.uiuc.edu/svn/sp10/cs428/JNI/. Theproject simply be added to the active workspace. See the GUI tests section below for additionalrequired dependencies to be able to run those tests.

6.2 Running the plug-in

After installing the plug-in from the update manager, restart Eclipse when prompted. WhenEclipse comes back up, all features should be available to use.

• The wizard feature can be activated via the “File → New → Other...”, under the JNI category.

• The content assist feature can be activated by pressing <Ctrl+Space> in a text editor for a Cfile.

• The refactoring feature can be activated by right-clicking on a Java method name and navigatingto the JNI Refactor menu.

6.3 Running the tests

Ensure that you have the JDT, JUnit 4, and the Eclipse SDK installed before running the tests.

6.3.1 Automated AST Handler tests

To run the ASTHandlerTest, run the launch configuration labeled “Launch ASTHandler Tests.launch”in the test directory. This may take several seconds and will pop up a new instance of Eclipse as ittests the functions. As usual JUnit output, if the tests pass, the JUnit bar will turn green; otherwise,it will turn red.

6.3.2 Automated Emitter tests

To run the EmitterTest, run the launch configuration labeled “Launch Emitter Tests.launch” in thetest directory. This may take several seconds and will pop up a new instance of Eclipse as it tests thefunctions. As usual JUnit output, if the tests pass, the JUnit bar will turn green; otherwise, it willturn red.

6.3.3 Manual Content Assist tests

The content assist function only has one success case (the menu appears with proposals) and onefailure case (the menu does not appear with proposals). To test it manually, perform the following:

1. Run the wizard and ensure that the C file is generated properly and added into the projectworkspace.

2. Open up the C file for edit. *Make sure that to change the current perspective to Eclipse CDTview.

3. Type in any arbitrary ASCII letters in the file, and press <Ctrl+Space>

4. The content assist menu should pop up listing all the proposals.

6.4 Automated GUI tests 23

5. 2 seconds later, a yellow box should pop up next to the menu of proposals displaying informationregarding each proposal.

6. Scrolling through the proposals should result in the information window to change to reflect thecurrent highlighted proposal.

7. Double-Clicking on the proposal, or pressing <Enter> should add the proposal string into thecurrent line containing the cursor in the editor.

6.3.4 Manual Refactoring tests

To manually test the AlterMethodSignatureAction, do the following:

1. Run the JediPlugin project as an Eclipse Application.

2. In the new Eclipse instance, create a new project and a new package in that project.

3. Use the new JNI generation wizard to create a new JNI class with methods that you wish totest the JNI refactoring on.

4. Right-click a method and navigate to JNI Refactor → Alter Method Signature...

5. After the refactoring engine completes, make sure that the JNI method signature in your .c and.h file corresponding to the refactored Java method is equivalent to that method’s signature.

6. Optionally, repeat steps 3-5 (or 4-5 if in the same class) for any other methods you wish to test.

NOTE: Overloaded methods are not supported at this time. For more information,see the documentation of the Refactoring component.

6.4 Automated GUI tests

You must ensure that the following dependencies are installed in Eclipse prior to running the tests:

• org.eclipse.ui

• org.eclipse.core.runtime

• org.eclipse.swtbot.eclipse.finder

• org.eclipse.swtbot.junit4 x

• org.eclipse.swtbot.swt.finder

• org.junit4

• org.hamcrest

The official list of dependencies can be found at: http://wiki.eclipse.org/SWTBot/UsersGuide#Configuration 2

6.4.1 Quick Description of what is tested

We have seven automated GUI tests. The following is a listing of each test and a brief descriptionof what is being tested:

• testMainSuccessCase: As per the name, this test is verifying the success of the main successcase for our plug-in. It runs the JNI Generation new class wizard from start to finish and thenafter a successful run, it verifies that the JNI Class java file, the C header file, and C source fileare each created properly in the correct location within the project.

6.4 Automated GUI tests 24

• testModifyExistingJNIClass: This test is similar to the main success case, but instead ofcreating a brand new JNI Class, this test first creates a normal Java Class and then uses theJNI Generation wizard to convert that Java Class into a JNI Class. After the wizard completes,it verifies the Java file, C header file, and C source file are all created in the proper locationwithin the project.

• testRefactorMethodSig: This test is designed to successfully refactor a method signature of anative method within a valid JNI class. ( See test notes for problem with this test )

• testMethodCreation: This test creates a new JNI class using the JNI Generation wizard, butunlike the main success case, this test generates several methods with varying parameter lengthsand method values. Specifically, this test verifies that the JNI Generation wizard can correctlygenerate parameter and return types of each of the primitive types, primitive array types, objecttypes, and object array types. It also verifies that varying parameter list lengths are handledproperly. Further, it verifies that the wizard can create static and non-static methods as well asvoid methods along with all of the visibility settings. ( See test notes for issues with this test. )

• testControlStateCorrectnessJCGPage: This test verifies that the JCGPage of the JNI Gener-ation wizard functions correctly. That is, it ensures that all of the UI controls react correctly touser input and force the user to provide valid values for each required field before allowing theuser to proceed to the next page or finish the wizard.

• testControlStateCorrectnessJNIClassPage: This test verifies that the JNIClassPage of theJNI Generation wizard functions correctly. That is, it ensures that all of the UI controls reactcorrectly to user input and force the user to provide valid values for each required field beforeallowing the user to proceed to the next page or finish the wizard.

• testAddMethodDialogControlState: This test verifies that the AddMethodDialog of the JNIGeneration wizard functions correctly. That is, it ensures that all of the UI controls reactcorrectly to user input and force the user to provide valid values for each required field beforeallowing the user to proceed to the next page or finish the wizard.

6.4.2 How to run the tests

To run the GUITest, run the launch configuration labeled “Launch GUI Tests.launch” in the testdirectory. This may take several seconds and will pop up a new instance of Eclipse as it tests thefunctions.

6.4.3 What to expect during the tests (visually)

The tests will launch a single new instance of Eclipse in which the test will run one after another.You will see a lot of windows and dialogs opening and closing rather quickly. You will also see fieldsbeing populated and buttons being clicked. However, you will not see menus being navigated. Onceall of the desired tests have run, the new instance of Eclipse will close.

6.4.4 What results to expect from the tests

Every test should pass whether you run them all in succession or one at a time. There are knownreasons for why some of the tests may appear to fail, but these failures are infrequent and entirelyrelated to the incubation status of SWTBot. We worked around them as best as possible and havetaken several steps to reduce the frequency in which they occur. It is unlikely that you will see thetests fail. That being said, we have provided a section below titles “Known Issues” which documentsall of the known issues with SWTBot in relation to our test suite.

6.5 Known Issues 25

6.5 Known Issues

6.5.1 Automated GUI tests

The testMethodCreation test relies on a very hacky method named editJNIArg within the JNIArgTesterclass. This method relies on the ability to set the value of a cell within a table using SWTBot. How-ever, it is documented that SWTBot does not yet support this functionality. As a workaround, wewere able to write the desired value to a temporary text field, select the value, tell SWTBot to useCTRL-C to copy the value, select the desired cell, and use CTRL-V to paste the value into the cell.This is a bit of a hack, but it is almost a good workaround until SWTBot implements the ability towrite to a cell. It is almost a good workaround for the following reason: Eclipse sometimes overwritesthe copy buffer when writing errors to the console, so it may be the case that the pasted value is notthe desired value, but rather some random error message. To ensure this would not cause the test tofail, we wrapped the copy paste procedure in a while loop which verifies that the value pasted into thecell is the value initially written to the temporary field. However, this would potentially loop infinitelyso we added a try limit of three to prevent this. Thus this test may fail if the copy paste does notsucceed after three tries. In our testing procedures, we only ever saw one case where the test wouldneed to try a second time, but it is no less possible.

The testRefactorMethodSig test does not actually test what we say it tests. That is, it wouldtest the desired functionality, but SWTBot does not yet support navigating multilevel context menusand so we cannot actually invoke the Refactor JNI Method Signature menu option automaticallybecause of this. The test does successfully get all the way to the point at which is would navigatethe menu and open the dialog, but because SWTBot is incomplete, we have commented out the linewhich would navigate the context menu. However, in testing, we did find that SWTBot can find thatthe menu item exists, and it is true that the dialog used to refactor the method signature is fullytested in our other tests. Thus the test is nearly complete as is.

SWTBot automated tests are very precise, or rather, require exact precision. If an unexpecteddialog or window appears during a test, it will change the focus within the SWTBot and cause thetest to fail because the SWTBot cannot find the correct ui controls to complete the test. We noticedthis primarily when running the tests on an Eclipse install with the Android SDK plugin installed.When the new instance of Eclipse is launched for the tests, it does not have any saved configurationssuch that it allows the testing process to be idempotent. However, the Android SDK plugin has apopup dialog which asynchronously appears and prompts the user to set the location of the AndroidSDK directory. This dialog would confuse the test and cause it to fail every time. In order to avoidthis issue, it is recommended that, when running a test, you set the run configuration for the test toonly use selected plugins. Then, only select the required plugins so that others, such as the Androidplugin, will not confuse the test.

Furthermore, on different machines, asynchronous tasks take different amounts of time to execute,and thus complete at different times. In several of our tests, we have the line bot.sleep(5000) orsimilar. This line is there to ensure that the necessary asynchronous tasks have time to completebefore the test tries to continue. This is most notable in the case where the test clicks “Finish” withinthe JNI Class wizard. At this point, the wizard will run javah in the background and once complete,refresh the project in the workspace. If the test tries to continue before the refresh is completed, itwill fail to locate the desired files within the package view. If you find that a test is failing on anassertTrue(verifyFileCreated...), it is most likely the case that the sleep time is insufficient andneeds to be increased. The time listed above, “5000,” is the desired sleep time in milliseconds. Thistime was sufficient for all of our testing purposes without causing unnecessarily long pauses duringtesting.

6.5.2 Automated ASTHandler and Emitter tests

If the ASTHandler or Emitter tests do not pass from a clean checkout, it may be because ofthe test-workspace is not in an expected state. As a workaround, completely delete the workspace

6.5 Known Issues 26

folder from the project, create a new folder with the same name, switch your workspace to that newfolder, create two new projects in the test-workspace according to how the original test-workspacewas structured, and then switch back to development workspace and run the tests again. Afterwards,the tests should pass.