X

Geertjan's Blog

  • January 13, 2006

Publish Plug-ins Painlessly...

Geertjan Wielenga
Product Manager
As so often before, I'm guessing I'm doing something wrong—because, what I thought would be a painful process is actually pretty simple (and will be simplified even further in upcoming releases). First, I'll show you how you can get plug-in modules from my Update Center. This way, you'll start off by seeing the result of the end-product first. Then, I'll show you how I can get your plug-in modules—via your Update Center. If you're not completely (or at all) clear about what an "Update Center" actually is, don't worry. I was the same way until not very long ago (in fact, yesterday). But, once you've worked through this blog entry, it will be 100% clear to you what an Update Center is, what it does, how to make one, and what to do with it. I'm pretty sure you'll like it and, once you see how simple it all is, you'll be creating your own before you know it.

So, there are two sections... here's the first:

Using Someone Else's Update Center

  1. In the Advanced Options section of the Options window (under the Tools menu), right-click "Autoupdate Types" and choose New > General Update Center, as shown below (click to enlarge each of the screenshots below):


  2. When you are prompted for an "Object Name", type this:

    NetBeans 5.0 Beta Plug-in Module Sample Update Center
  3. A new node is added with the specified name. Select it. A few fields appear on the right-hand side of the Options window. In Server URL, fill in the following:

    http://blogs.sun.com/roller/resources/geertjan/updates_geertjan.xml

  4. Click Close, to exit the Options window. Then open the Update Center Wizard (also under the Tools menu). Tada! Here you see what you should now be seeing:



    (By the way, I don't know whether you have the "Development Update Center", because maybe you're using a Beta release, and the Development Update Center is only available to Development Builds of the IDE. But, if you followed the steps above, you should definitely have the "NetBeans 5.0 Beta Plug-in Module Sample Update Center".)

  5. Select the new Update Center and click Next. Now you should see a list of plug-in modules:



    (By the way, you might have seen some or all of the above plug-in modules before..? In the tutorials, maybe..? The difference is that here I've named them after the NetBeans API which they illustrate. But, for example, the first item in the "Miscellaneous Functionality" is none other than Ludo's Google toolbar.)

  6. Browse through the list—notice the extensive descriptions of what each plug-in module does? Helpful, isn't it? It'd be cool if other providers of plug-in modules would do the same. (Use the "Long Description" box in the Display panel of the project's Project Properties dialog box.) Here's a rule of thumb: better to have too much info in that description box than too little... (None at all just sucks, but I've come across that more than once.)

  7. Now click the "Add All" button. (That's right, be greedy.) Click Next and, after the plug-in modules have been downloaded, click Next again. Select all the checkboxes on the left-hand side and specify that you don't mind the fact that the plug-in modules are unsigned. (Sorry, that's something I still need to work on.) Then click Finish.

  8. Look at the bottom left-hand corner of the IDE and wait until you see this:

  9. Now go to the New Project wizard (under the File menu). Notice that there is a new category called "NetBeans API Implementations", within the "Samples" category:


    Congratulations! You have successfully used my Update Center.

  10. Now select whichever sample grabs your fancy and then click Next and Finish. You'll find that a complete, functioning, plug-in module opens in the IDE. The name and the description of the plug-in module indicate what it does—in each case a NetBeans API is illustrated. In each case, a tutorial is available to explain how the plug-in module works and how to build it from scratch.

  11. Next, ask yourself: "Do I have a plug-in module lying around that is not too complex? Does it illustrate how one of the NetBeans APIs is used? In particular, does it illustrate code completion? Or code folding? Or hyperlinking in an editor?"

  12. If you answered "yes" to any of the questions above (or even "maybe"), please let me know as soon as possible—more tutorials are needed (especially on code completion, code folding, and hyperlinking) and I'd like to add the resulting plug-in modules to my update center.

  13. Finally, go to the Options window again. Take a look at the first panel (called "General"). At the bottom of this panel you can specify how frequently the IDE will check whether your registered Update Centers have new or changed plug-in modules. And then the IDE will tell you. Handy, right?

Now that you know how to use someone else's Update Center, let's make your own.

Creating Your Very Own Update Center

The principle of creating your own Update Center is incredibly simple. Take another look at step 3 above. When you're defining the Update Center, you specify a URL to an XML file:

http://blogs.sun.com/roller/resources/geertjan/updates_geertjan.xml

To see what that XML file looks like, click here. Each plug-in module is described in this XML file. The XML file is called the autoupdate descriptor. This is what just one of the plug-in module's descriptions looks like:

<module codenamebase="org.netbeans.modules.javahelpapisample"
homepage=""
distribution="./org-netbeans-modules-javahelpapisample.nbm"
license="no-license.txt"
downloadsize="555189"
needsrestart="false"
moduleauthor=""
releasedate="2006/01/13"
>
<manifest OpenIDE-Module="org.netbeans.modules.javahelpapisample"
OpenIDE-Module-Display-Category="Plug-in module samples"
OpenIDE-Module-Implementation-Version="060113"
OpenIDE-Module-Long-Description="This project sample adds a helpset to the IDE's help system.
Go to Help > Contents and then look at the last section --
it should be called "My Plug-in" and it should contain
one topic. You can use this project sample to understand how helpfiles
work. Alternatively, you can just take this sample, and then add
help topics to it. In other words, this can be a template on top
of which you build your own helpset."
OpenIDE-Module-Module-Dependencies="org.jdesktop.layout/1 > 1.4, org.netbeans.modules.projectapi/1 >
1.10, org.netbeans.modules.projectuiapi/1 > 1.14.0.5,
org.openide.awt > 6.8, org.openide.dialogs > 6.6,
org.openide.filesystems > 6.5, org.openide.loaders > 5.10,
org.openide.util > 6.9"
OpenIDE-Module-Name="JavaHelp API Sample"
OpenIDE-Module-Requires="org.openide.modules.ModuleFormat1"
OpenIDE-Module-Specification-Version="1.0"
/>
</module>

Everything you see in the description above is defined in the plug-in module's Project Properties dialog box—in the Libraries panel, the Display panel, and in the Packaging panel. So you define all the properties above (or, actually, in most cases the IDE defines them for you, when you create the plug-in module project and later when you use New File wizards, but you can finetune them in these panels in the Project Properties dialog box if necessary).

So, all you need to do to create your own Update Center is (1) define the autoupdate descriptor, (2) provide the NBM file(s) described in the autoupdate descriptor, and (3) put the autoupdate descriptor and the NBM file(s) somewhere where your target audience can reach them. (Make sure that the autoupdate descriptor's distribution element point to the location and name of the NBM file in question. You can use relative paths, as shown in the example above.) Then tell whoever need your modules about the URL to the autoupdate descriptor (just like I did in step 3 of the previous section).

It's not quite as simple as it sounds, though. The main problem is: "How do I create the autodescriptor file?" It's not much fun to do it manually. In fact, it's really quite hard, especially the OpenIDE-Module-Module-Dependencies. And there's nothing in NetBeans IDE 5.0 to simplify the job of putting this descriptor together. However, since issue 64426 was fixed, you can use a new menu item in the development build of the release currently known as "5.1":


When you install this development build, you can put all your plug-in modules together into a module suite and then, when everything is nicely assembled, you can choose "Create NBMs":


When you do this, the IDE creates an NBM file for each plug-in module that is part of the suite. It also creates, in the same "updates" folder where the NBM files are created, a file called updates.xml. This is the autoupdate descriptor, created for you by the IDE. The only tweak I needed to perform was to rearrange the entries a bit and to give the items some structure, by means of <module_group name> tags. (You see these module groups in the Update Center.) I'm assuming these tweaks will not be necessary in the future, because this functionality is being worked on as we speak.

Now here's a great tip—since it's so easy to create an Update Center, why not use it to store backups of your applications? So, let's say you have an application open in the IDE (it could be any application, such as, for example, a web application, a standard desktop application, or a plug-in module). Use the NetBeans Project Sample Module Tutorial to create a plug-in module that contains your application as a sample. Then create an NBM file (created by means of one item, selected by right-clicking the plug-in module's node in the Projects window). Then just put the NBM file on a server somewhere far away (even on geocities.com or somewhere like that). All you need to do is make sure that the plug-in module is described in an autoupdate descriptor. Then, set up the Update Center in the IDE, as described in the first section, by pointing to the autoupdate descriptor from inside the Options window. And once you've done that, your application is available from the Update Center Wizard, from where you install it into the New Project wizard (thanks to the instructions provided in the tutorial). It seems a bit lengthy, but it really isn't. Uploading the NBM file that contains my application (as a project sample) into my blog literally takes seconds. And, once you've defined the autoupdate decriptor once you don't really need to do so again (unless you keep developing the module, so that its dependencies change, or its description, etc).

So, anyway, that's all there is to it. If you follow the above instructions you too will have your own Update Center. And the funny thing that you realize, at the end of the whole story, is that an Update Center is nothing more than an XML file plus the NBM files that you want to distribute. It couldn't be much easier, could it?

Is there anything else anyone needs to know about Update Centers?

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.