X

Geertjan's Blog

  • January 13, 2006

Publish Plug-ins Painlessly! (Part 1)

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.

    Note: If you're not using a recent post-5.0 development build, you'll probably encounter problems with the versions of the module dependencies...

  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 the description of just one of the plug-in modules 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 points 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 needs 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 autoupdate descriptor?" 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?

Update: See Part 2 for another example of an Update Center... and a very cool module!

Join the discussion

Comments ( 12 )
  • Alexis MP Friday, January 13, 2006
    I have dependency problems installing the modules using NB RC1:
    http://blogs.sun.com/roller/resources/alexismp/GeertjanUpdate.png


    I love the idea of documenting the Update Center infrastructure. Thanks for doing this!
  • Jiri Rechtacek Friday, January 13, 2006
    Excellent Geertjan. Funny and useful guide how publish own plugin or create own Update Center. Thank you.
    Note that a plugin's NBM can be hosted on an another site then Update Center is hosted. URL of location of the NBM write into <distribution> attribute of Update descriptor.
    And a small hint: Do you want add some HTML tag into Long-description in Update description? Yes, you can. However you have to escape HTML tag but the Update Center Wizard can is reading and rendering these tags. The description can contain a http link to an tutorial about this plugin
  • Jesse Glick Friday, January 13, 2006
    Re. creating groups inside an update descriptor: the default target in suite.xml will just put everything into one group. But you can override that target and use <group name="My Group"> to wrap groups of NBMs according to taste.
  • Geertjan Saturday, January 14, 2006
    Alexis, yes. That's because I'm using a post-5.0 dev build. (You can download it from www.netbeans.org Download page.) Not sure how to get around this. Currently, to use my Update Center, you MUST have a dev build (so, not Beta or RC or anything like that, but something from AFTER that). It's also good to use one of these dev builds because only the dev builds have the "Create NBMs" menu item on the suite project node. If you don't have that, you can't generate your own autodeply descriptor... But when 5.0 comes out I will make a new version of everything in my Update Center, specifically for 5.0, so that it's possible to access the samples if you're using 5.0.

    Jiri, thanks for the additional info. I will try out your hint about the HTML in the long description.

    Jesse, interesing. I hadn't thought of getting the target and modifying it like that. I will look at that too.

  • huntch Saturday, January 14, 2006
    Really cool. This is a great way for folks building rich client applications to distribute updates to their applications. One could also use this mechanism as a way for companies who have firewalls that prevent external access to make updates or additional plugins available. They could setup a "specialized" internal update center where they could find updates and additional plugins. It could also help those large companies who have help desks for a specific netbeans IDE configuration of plugins to limit what developers are using for plugins and to be able to deliver updates, bug fixes, etc to everyone they are supporting. Thanks for sharing!
  • Geertjan Sunday, January 15, 2006
    Hi Charlie, thanks for those comments. I think there are many ways in which the Update Center functionality can be used. I need to add something soon on how "versioning" is done. In other words, after you install NBMs from an Update Center, when you go back to the same Update Center, the IDE will tell you that there are no NBMs there, unless there is a new version of an NBM. This is quite handy (and works well with the notification that you can set in the General panel of the Options window). This lets you provide updates very easily. (I'd like some way that that could be announced via e-mail: whenever I publish a new version of a module, I'd like an e-mail notification to be sent to everyone who installed previous version(s) of my module.)

    By the way, in my previous response to Jesse, Jiri, and Alexis, I erroneously referred to something called "autodeply descriptor". Of course, I mean "autoupdate descriptor".

    Thanks for the comments and, if anyone out there is trying out Update Centers for themselves, you can let me know and I'll link to it from this blog!

  • Luan O'Carroll Wednesday, January 18, 2006
    Is there an API or any way of controlling access to the update centre, or checking licensing information say for commercial modules?
  • Geertjan Monday, August 21, 2006
    There's a new wizard called "Update Center" in NetBeans IDE 5.5 that automates the process of registering an update center. The end user will not need to manually register the URL to your XML file if you use this wizard. Plus, the IDE automatically generates the XML file, if you use the "Create NBMs" menu item on the module suite (also in NetBeans IDE 5.5). (Both these features are also available in 5.0, if you use the Module Development Update 1 module.)
  • kousik Tuesday, October 31, 2006
    >I could able create my own update center and I executed it . In the update center wizard, I added the modules from the list of modules and accepted the license agreements. But from then, I get a DOWNLOAD ERROR. I get a message box saying "The download of <modulename> failed. Do you wish to download this module again?"
    I hosted all the nbm files and updates.xml in the same path in a local web address, and the path for nbm files i gave as direct http address.
    Please help me out how to resolve this Download error.
  • Fred Bulah Friday, February 23, 2007
    Hello Geertian,
    Very good article. I am a long-time Eclipse user, but I am now using NetBeans for a new project. What I need to do is build a module as part of an RCP application that automatically retrieves other modules from an update center based on the user's login credentials. In essence, I need to invoke the update mechanism programmatically at start-up of the RCP application. Is there an example of how this could be done? Could you provide any pointers and/or guidance? Any and all help would be greatly appreciated. Thanks in advance.
    -Fred
    PS: one other question ... how can you pass command line args (-D<arg>) to a NB RCP app? (this is fairly simple in Eclipse but I'm having some difficulty doing this in NB)
  • Geertjan Friday, February 23, 2007
    Hi Fred, welcome to the world of NetBeans! Both your questions are interesting and I will investigate them. In the meantime, I highly recommend that you join dev@openide.netbeans.org (click here to get to the archives) and that you ask your question there. Please keep in touch and let me know how you're getting on.
  • Doug Wednesday, August 13, 2008

    In response to a posting by kousik on October 31, 2006... I came across the same issue. It is because the .nbm MIME file extension needed to be added to the hosting IIS server. See http://support.microsoft.com/default.aspx?scid=kb;en-us;326965 for more information.


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