Creating Your Own Extension Points Its Easier Than

Creating Your Own Extension Points (It's Easier Than You Think!) *All images are royalty-free courtesy of http: //SXC. hu © 2008 by Mark Melvin; made available under the EPL v 1. 0 | March 13 th, 2008 | ON Semiconductor

Presentation Overview • Introductory material • The Eclipse extension registry • A simple application • Refactoring for extensibility • Creating your own extension points • Putting it all together • Beyond the basics • Things to remember • Questions? Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Introduction • Who am I? w I am not an expert (but I know some stuff) w Been developing Eclipse plug-ins for over 5 years w Not a committer, but have fairly broad knowledge of internals w Written many extension points and learned from the process Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

What Are Extension Points? • Extension Point w A unit of functionality declared by a plug-in in its plugin. xml file using the <extension-point> element. • Has an id, name, and optional schema attribute • What you are here to learn more about Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

What Are Extensions? • Extension w A particular contribution to an extension point declared in the plugin. xml file of your plug-in using the <extension> element. • Can contain many sub-elements and attributes as defined by the extension point to which you are contributing • What you’ve been writing as plug-in developers Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Why Do I Need Extension Points? • Extension points can promote modularity and re-use • Extension points can reduce coupling and increase cohesion • Well-designed extension points are like well-designed APIs, but with additional benefits Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Advantages of Extension Points • Extension points can be dynamic w Code required but Eclipse platform does the heavy-lifting • Eclipse classloading advantages • You get tooling and documentation for free Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

The Bottom Line • You don’t need extension points …but you should use them! Can you imagine an Eclipse without them? Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

The Eclipse Extension Registry *All images are royalty-free courtesy of http: //SXC. hu © 2008 by Mark Melvin; made available under the EPL v 1. 0 | March 13 th, 2008 | ON Semiconductor

The Extension Registry • We’ve all seen this diagram before, right? Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

The Extension Registry: Lazy Loading • In general, Eclipse is lazy (get a job, ya bum!) • First execution of Eclipse scans metadata (plugin. xml) for all bundles • Subsequent runs use cached information unless: w Cache appears invalid or corrupt w You specify –clean on the command line • When new bundles are installed, their metadata is also parsed and cached • More info: w org. eclipse. core. runtime. adaptor. Eclipse. Starter w org. eclipse. core. internal. registry. Extension. Registry Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

The Extension Registry: Lazy Loading (cont’d) • Cached metadata or not, Eclipse still does not start your bundle activator until it has to • Metadata-only can be used to create GUI contributions • Poorly-designed extension points can lead to unnecessary bundle starts Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Extension Sequence Diagram • What happens when an extension is loaded? *Image courtesy of Neil Bartlett from A Comparison of Eclipse Extensions and OSGi Services Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

A Simple Application Eclipse. Eyes © 2008 by Mark Melvin; made available under the EPL v 1. 0 | March 13 th, 2008 | ON Semiconductor

Eclipse. Eyes: An Overview • A simple plug-in based on built-in PDE action handler sample • Transparent shell based on SWT snippet #219 with a simple eyetracking algorithm Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Eclipse. Eyes: Summary • Wow! That’s incredibly useless! • How can we make this more extensible and modular and more annoying at the same time? • I’m glad you asked! This looks like the perfect starting point for… An Eclipse Assistant! Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Adding Extension Points Goal: w Re-factor this plug-in to provide a common Eclipse Assistant framework to which other people can contribute additional Eclipse Assistant characters and custom behaviors. Requirements: w Framework should provide all character-independent code w Must be able to contribute new images, as well as custom animation and character behaviors w Functionality must be provided through extension points w Resulting framework must survive extension registry changes without restarting Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Adding Extension Points (continued) Procedure: w Identify the common and re-usable bits in the existing plug-in and re-factor w Figure out what you want to be extensible (contributable) and come up with a reasonable extension point schema w Consume this new framework ourselves by contributing the existing Eclipse. Eyes character (eating our own dog food) Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Refactoring for Extensibility *All images are royalty-free courtesy of http: //SXC. hu © 2008 by Mark Melvin; made available under the EPL v 1. 0 | March 13 th, 2008 | ON Semiconductor

Refactoring Eclipse. Eyes • What should be part of the framework? w w w Command to toggle visibility Background image loading Preferences (if any) Event handling framework (mouse, keyboard, timer) Extension lifecycle management • What should be extensible? w Character name w Background image w Animation providers • Gray areas w Frequently-used animations (eye tracking) w Annoying message generation Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

The Eclipse. Assistant Plug-In Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

The Eclipse. Assistant Plug-In (continued) • Character. Contribution w Has an id, name, and background image w Has optional IRenderers for animation layers • IRenderer w Has a z-order, and draws artifacts onto a GC w Has optional event-based triggers (mouse, keyboard) Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Creating Your Own Extension Points *All images are royalty-free courtesy of http: //SXC. hu © 2008 by Mark Melvin; made available under the EPL v 1. 0 | March 13 th, 2008 | ON Semiconductor

Declaring an Extension Point • You declare an extension point in plugin. xml • Schema is optional, strictly speaking (but you should always provide one!) • Don’t forget to update MANIFEST. MF (Don’t worry – the PDE has got your back!) Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

The Extension Schema Editor • The PDE provides powerful tools for editing extension point schemas Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

The Extension Schema Editor - Overview Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

The Extension Schema Editor - Definition • Define your schema’s structure and related documentation • Start by creating base elements • Next add element attributes boolean string java resource identifier (proposed for 3. 4) • Connect together with choice or sequence compositors Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

The Extension Schema Editor - Source • You can always edit raw XML if you prefer, on the Source page • PDE will magically keep everything synchronized Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Contributing Eclipse. Eyes • The same as contributing to any other Eclipse extension point • Edit plugin. xml and add an extension to the extension point we just created • This is enough to create entries in the extension registry, but we’re not quite there yet • We still need to read the extension registry and instantiate objects! Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Putting It All Together *All images are royalty-free courtesy of http: //SXC. hu © 2008 by Mark Melvin; made available under the EPL v 1. 0 | March 13 th, 2008 | ON Semiconductor

Reading the Extension Registry • Not particularly hard, but think ahead • The basic principle is this: • Instances of IExtension hold information about the declaring plug-in, and a Java representation of the XML (from plugin. xml) as a tree of IConfiguration. Elements. • Use this information to construct and cache proxy objects Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Reading the Extension Registry (continued) • A lot of generic machinery but no public, reusable Registry. Reader class* • See org. eclipse. ui. internal. registry. Reader for a reasonable starting point • IConfiguration. Elements are (potentially) shortlived and should be checked for validity if cached • If your registry reader is dynamic-aware, this is not a concern *https: //bugs. eclipse. org/bugs/show_bug. cgi? id=221603 Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Reading the Extension Registry (continued) • An example proxy object implementation Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Reading the Extension Registry (continued) • You have translated XML markup from plugin. xml into Java objects that contain data • Useful classes and interfaces: Platform, IExtension, IConfiguration. Element, IExecutable. Extension, Extension. Tracker, IExtension. Change. Handler • Still more effort required to make this more useful • More advanced topics: w Creating Java objects from class names specified in extension point contributions (not so advanced…) w Respond to changes in extension registry Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Beyond the Basics *All images are royalty-free courtesy of http: //SXC. hu © 2008 by Mark Melvin; made available under the EPL v 1. 0 | March 13 th, 2008 | ON Semiconductor

When to Read the Extension Registry • When should you read the registry? w NOT on startup w Be as lazy as possible • Create and initialize the registry reader on first access w Start listening for changes to the extension registry • Defer reading extension point contributions until you need them • Cache extension point contributions, reloading if required on registry change • Clean up on plug-in shutdown Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Contributing Java Objects • In your schema, use the “java” attribute type • Optionally force consumers to extend a super class or implement an interface w Super class or interface provided by plug-in providing extension point (must be publicly exposed) • Use IConfiguration. Element#create. Executable. Extension to create instance and cast Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Contributing Java Objects (continued) • Default behavior calls 0 -argument constructor • To pass additional initialization data w Ensure your class implements IExecutable. Extension w After 0 -argument constructor is called IExecutable. Extension#set. Initialization. Data will be called w Method signature: public void set. Initialization. Data(IConfiguration. Element config, String property. Name, Object data) throws Core. Exception; Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

IExecutable. Extension#set. Initialization. Data • Two methods of supplying initialization data: w Supply parameters after classname <action run="com. example. External. Adapter: . /cmds/util. exe -opt 3"/> w Supply parameters as nested <parameter> elements <action> <run class="com. example. External. Adapter" plugin="com. example"> <parameter name="exec" value=". /cmds/util. exe"/> <parameter name="opt" value="3"/> </run> </action> • class, plugin and parameter attributes are “magic” (required) • Read Javadoc for more details Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

IExecutable. Extension#set. Initialization. Data • Clever extension point schema construction allows both initialization forms with automatic fall-through w Specify an optional “java” attribute, and an optional nested construct w Attribute will be tried first, followed by nested construct • See IExecutable. Extension#set. Initialization. Data Javadoc for more details Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Responding to Extension Registry Changes • When extensions are added or removed you should handle it gracefully • Extension. Tracker makes it easy to detect fine-grained extension registry changes • After initial registry read, start listening for changes Use: org. eclipse. core. runtime. dynamichelpers. Extension. Tracker Implement: org. eclipse. core. runtime. dynamichelpers. IExtension. Change. Handler public void add. Extension(IExtension. Tracker tracker, IExtension extension) public void remove. Extension(IExtension extension, Object[] objects) See: IExtension. Tracker#register. Handler, IExtension. Tracker#register. Object Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Responding to Extension Registry Changes • Register your handler IExtension. Tracker tracker = Platform. UI. get. Workbench(). get. Extension. Tracker(); IExtension. Registry xregistry = Platform. get. Extension. Registry(); tracker. register. Handler(this, Extension. Tracker. create. Extension. Point. Filter ( xregistry. get. Extension. Point(“my. extension. point. id”))); • Register your objects Character. Contribution character =. . . ; IExtension. Tracker tracker = Platform. UI. get. Workbench(). get. Extension. Tracker(); tracker. register. Object( character. get. Configuration. Element(). get. Declaring. Extension(), character, IExtension. Tracker. REF_STRONG); • Respond to change public void add. Extension(IExtension. Tracker tracker, IExtension extension) {. . . } public void remove. Extension(IExtension extension, Object[] objects) {. . . } Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Responding to Extension Registry Changes • At a minimum: w Delete cached items when registry changes w Rebuild cache from Extension Registry on next access • It is relatively simple to be dynamic, so do it! w Search for implementors of IExtension. Change. Handler for examples • Be careful of SWT threading issues w Use Platform. UI. get. Workbench(). get. Extension. Tracker() for UI contribution changes Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Things to Remember *All images are royalty-free courtesy of http: //SXC. hu © 2008 by Mark Melvin; made available under the EPL v 1. 0 | March 13 th, 2008 | ON Semiconductor

Things to Remember • Extension points are for everyone • Be as lazy as possible • Contribute (and expose!) abstract classes and interfaces you intend consumers to implement / extend • Don’t be too lazy! w Always fill in schema documentation w Always be dynamic (Extension. Tracker) • The PDE is your friend w Don’t forget about the Plug-in Registry View! Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0

Demo Code is available: http: //eclipsesvn. cloudsmith. com/eclipsecon 2008/ http: //public. xdrive. com/opc/XDPC-3675 ni. WSq. Diu. OChp. GLl. Icv 80 ROHqoo. Xe/ *All images are royalty-free courtesy of http: //SXC. hu © 2008 by Mark Melvin; made available under the EPL v 1. 0 | March 13 th, 2008 | ON Semiconductor

Questions? *All images are royalty-free courtesy of http: //SXC. hu © 2008 by Mark Melvin; made available under the EPL v 1. 0 | March 13 th, 2008 | ON Semiconductor

Useful Resources • Eclipse: Building Commercial-Quality Plug-ins (2 nd Edition), Eric Clayberg and Dan Rubel • Java(TM) Developer's Guide to Eclipse, The (2 nd Edition), Jim D'Anjou, Scott Fairbrother, Dan Kehn, John Kellerman, Pat Mc. Carthy • Getting started with Eclipse plug-ins: creating extension points, Alex Blewitt http: //www. eclipsezone. com/eclipse/forums/t 97608. rhtml OSGi-Related Information • Eclipse Extensions vs OSGi Services, Neil Bartlett http: //neilbartlett. name/blog/2008/01/22/eclipse-extensions-vs-osgi-services/ • Getting Started with OSGi (webinar), Neil Bartlett http: //live. eclipse. org/node/407 Creating Your Own Extension Points | It’s Easier Than You Think! | © 2008 by Mark Melvin; made available under the EPL v 1. 0