RESOLVED - bug 248859: Out of date article on download pages
https://bugs.eclipse.org/bugs/show_bug.cgi?id=248859
diff --git a/.htaccess b/.htaccess
index 9d9c736..0c8be40 100644
--- a/.htaccess
+++ b/.htaccess
@@ -61,4 +61,7 @@
Redirect permanent "/articles/Article-EclipseDbWebapps/article.html" http:/articles/article.php?file=Article-EclipseDbWebapps/index.html
#Updated JFace Wizards
-Redirect permanent "/articles/Article-JFace Wizards/wizardArticle.html" http:/articles/article.php?file=Article-JFaceWizards/index.html
\ No newline at end of file
+Redirect permanent "/articles/Article-JFace Wizards/wizardArticle.html" http:/articles/article.php?file=Article-JFaceWizards/index.html
+
+#Updated JFace Wizards
+Redirect permanent "/articles/Article-Update/keeping-up-to-date.html" http:/articles/article.php?file=Article-Update/index.html
\ No newline at end of file
diff --git a/Article-Update/index.html b/Article-Update/index.html
new file mode 100755
index 0000000..6303106
--- /dev/null
+++ b/Article-Update/index.html
@@ -0,0 +1,697 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+ <head>
+ <title>How To Keep Up To Date</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
+ <link href="../article.css" type="text/css" rel="stylesheet">
+ </head>
+<body>
+
+<h1>How To Keep Up To Date</h1>
+<div class="summary">
+ <h2>Summary</h2>
+ <p>This article shows you how to create and publish
+ bundles of plug-ins (called features) to an update site so that customers can
+ download and install them directly into Eclipse using the Eclipse update
+ manager. This has many advantages over the low tech way of delivering new or
+ updated plug-ins in a zip file that someone manually unzips into the directory
+ where Eclipse is installed. </p>
+ <div class="author">By Dejan Glozic, IBM and Dorian Birsan, IBM</div>
+<div class="copyright">Copyright © 2003,2006 IBM Corporation.</div>
+ <div class="date">August 27, 2003 (Appendix added January 13, 2004)</div>
+</div>
+
+<div class="content">
+<H2>Staying up to date</H2>
+<P>More often than not, software products are out of date as soon as they appear
+on the market: new features and bug fixes are already available before the CD's
+hit the shelves and web sites provide links for downloading. Eclipse based
+products are no different. Over the course of a project, remember how many times
+you exchanged plug-ins using email attachments with the suggestion 'just unzip
+into the Eclipse directory'. Of course, it works. But would you sell a product
+with 500 plug-ins for $2999, then send updates to customers by email with
+similar instructions? Or post hundreds of zip files on a web site, along with
+installation instructions ?</P>
+<P>In the real world where commercial products are built on top of Eclipse
+technology, new plug-ins and updates to existing ones must be delivered in a
+more convenient way. Another consequence of charging people for software is that
+there are legal ramifications to reckon with. For this reason, form
+has a component that deals with installing and updating plug-ins that is both
+convenient and keeps your company's lawyers happy. </P>
+<H3>Plug-ins are too small (even the large ones)</H3>
+<P>We already know that the basic building block of Eclipse functionality is a
+plug-in. Its manifest contains all the information required by Eclipse to
+successfully load it, contribute into the application and run. However, it is
+not particularly well suited for distribution. One reason is that a plug-in is
+functionally too fine-grained. We always start small, but real production
+quality plug-ins rarely come alone. A more realistic situation is to have
+several plug-ins working together to perform a useful function. Example: Java
+Tools consists of 9 plug-ins, PDE has 5 etc. These plug-ins require each other
+and go together - their usefulness is limited in isolation.</P>
+<P>To represent a unit of useful functionality Eclipse has a notion of
+<B>features</B>. Instead of saying 'take these 9 plug-ins that go together', you
+should be able to say 'take Java Tools'. </P>
+<P>The role of features is to allow providers to make collections of plug-ins
+that logically go together. These collections are made in such a way as to
+provide for easy transport over the network, have necessary legal and security
+mechanisms, and are modular to allow hierarchical product building.</P>
+<P>Features are designed to help in performing the three major tasks:</P>
+<OL>
+ <LI><B><A name=task1></A>Install new functionality into Eclipse products</B>.
+ This task allows you to add things you didn't have before and make your
+ product do more.
+ <LI><B>Update the plug-ins you already have to the newer versions</B>. This
+ task allows you to receive fixes and upgrades to the functionality you already
+ have. Official fix packs and emergency fixes for the pesky bugs that make your
+ life miserable all fall into this category.
+ <LI><B>Control which plug-ins should run when Eclipse starts</B>. This task
+ allows you to disable an entire group of plug-ins, thus making them invisible
+ to Eclipse run-time (note that they are still physically present in the
+ product). This comes in handy in large products where you have the whole slew
+ of features you don't care about at the moment and want to get rid of the user
+ interface artifacts you never use. </LI></OL>
+<P>Although features group plug-ins together, they are not containers. All the
+plug-ins are installed in the 'plugins' directory in the Eclipse product
+location. Features simply reference plug-ins (and fragments) that belong to
+them. This important property plays a major role in optimizing performance when
+downloading over the network. It allows Eclipse to download only the plug-ins
+that have actually changed between the two feature versions. It is easy to
+imagine why downloading 20 new plug-ins out of 500 makes a huge difference in
+this scenario.</P>
+<H3>What's in the manifest?</H3>
+<P>As plug-ins have <B>plug-in manifests</B>, features have <B>feature
+manifests</B>. The file name is feature.xml and it can contain the following
+things (the full DTD can be found in the reference section of the <A
+href="http://help.eclipse.org/ganymede/topic/org.eclipse.platform.doc.isv/reference/misc/feature_archive.html">Eclipse
+platform documentation</A>):</P>
+<UL>
+ <LI>Feature id, version, provider name, image to use in Eclipse
+ <LI>Short description, URL to long description, license agreement, copyright
+ statement
+ <LI>References to other features (for building complex feature trees by
+ inclusion)
+ <LI>Dependencies (features can require presence of other plug-ins or features
+ as a prerequisite for installation)
+ <LI>List of plug-ins and fragments that belong to the feature
+ <LI>List of data archives that belong to the feature (normally go together
+ with the custom install handler) </LI></UL>
+<P>This list is not complete but is fairly representative. A manifest file can
+contain translatable content but it is better to place it in
+feature_<NL>.properties files that will be picked as Java resource bundles
+based on the current locale. This is analogous to the way NL content is handled
+for plug-ins.</P>
+<H3>Where features live</H3>
+<P>Features exist in two major places and incarnations: <B>installed</B> (in the
+Eclipse product) and <B>packaged</B> (on the server as part of the update
+site).</P>
+<P>Imagine for a second that Eclipse is completely empty i.e. has no plug-ins
+and features. To get any functionality into it, you would need to download
+features from the server (see <A
+href="http://eclipse.org/articles/Article-Update/keeping-up-to-date.html#task1">task
+#1</A> above). For this to happen, features must be published on a HTTP server
+in the following way:</P>
+<UL>
+ <LI>All features must be packaged into the JAR archives (one per feature) and
+ placed into the directory called 'features'
+ <LI>All plug-ins must be packaged into the JAR archives (one per plug-in) and
+ placed into the directory called 'plugins'
+ <LI>An update site map (an XML file with the name 'site.xml') should be placed
+ in the root of the update site (the folder that contains 'features' and
+ 'plugins') </LI></UL>
+<P>Features and plug-ins are packaged into archives for easy transportation over
+the network. In addition, archives can be digitally signed. If you are charging
+for your software and want to protect your customers as they download updates
+from your site, it is a good idea to sign your archives using valid
+certificates. If not, Eclipse Update will warn your users that they are about to
+install an unsigned feature (a scary message indeed).</P>
+<P><IMG src="images/tip.gif" width="62" height="13"> Security issues with
+features should not be underestimated. Eclipse allows users to download new
+functionality from remote servers. A rogue plug-in can act as a perfect Trojan
+horse. It can look innocent enough and provide useful function while spawning
+threads in the background with full access to the local file system and the
+Internet (if connected). Beware of installing features from update sites you do
+not trust.</P>
+<P>By using Update Manager, we can connect to the update site and examine its
+content (we will talk more about this later in the article). Once we find
+features we want to install, we can bring up the install wizard and let it
+complete the installation.</P>
+<P>After we restart Eclipse, features and their corresponding plug-ins will be
+physically present in our product location. Features and plug-ins will not be
+archives any more: they will now be <B>installed</B>. All the features will be
+in the 'features' directory, and all the plug-ins in the 'plugins'
+directory.</P>
+<P>Of course, Eclipse is never empty to begin with. Every Eclipse product starts
+its life with a number of plug-ins and features. They were not installed using
+Update Manager - they were placed there as a baseline content. Initial update
+operations will be performed using this baseline as a reference.</P>
+<H3>Checking for updates</H3>
+<P>The easiest way to use Eclipse Update starting from a fresh Eclipse
+installation is to see if there are new versions of currently installed features
+available. Features typically have a URL to the site where updates can be found.
+When <B>Help>Software Updates>New Updates</B> is selected, Eclipse will
+connect to these update sites and try to find new versions of the already
+installed features. If found, they will be presented in the installation wizard.
+After accepting the license agreements, pressing <B>Finish</B> and completing
+the installation, your Eclipse product will have the latest updates.</P>
+<P>It is important to note that this operation is performed by Eclipse product
+customers - people that bought the product and want to have the latest service
+update of it. If you are the product provider, it is your responsibility to
+build the features and place them on the update site for your customers to find.
+In the following sections, we will learn how.</P>
+<H2>Time to get our hands dirty</H2>
+<P>Now that we understand the basics of the Eclipse Update mechanism, it is time
+to see it in action. We will use the 'Hello, World' plug-in, create a feature
+for it, publish it on an update site and then install it into another Eclipse.
+Since plug-in development is not the focus of this article, we will take
+advantage of PDE to do it fast.</P>
+<P><IMG src="images/tip.gif" width="62" height="13"> The goal of our example is
+to use one Eclipse product as a development environment, and publish a feature
+that can be installed into another Eclipse product. In order to keep things
+clean, we suggest you install two copies of Eclipse in your file system - one to
+use for development, and another to act as a product. Download the 2.1.1 version
+of Eclipse SDK from <A href="http://www.eclipse.org/downloads/">Eclipse.org</A>
+and unzip it into the two different locations.</P>
+<H3>Creating a feature</H3>
+<P>We will start by making the plug-in project by selecting
+<B>New>Project>Plug-in Development>Plug-in Project</B>. We will choose
+'com.example.xyz' for the project name (this will become our plug-in ID as
+well). We will accept the defaults and select 'Hello, World' template from the
+<B>Plug-in Code Generators</B> page.</P>
+<P>After pressing <B>Finish</B>, we should have the plug-in project created and
+visible in the Package Explorer. Newly created manifest file will be opened for
+editing in the PDE manifest editor. We should take this opportunity to test our
+new plug-in by following the 'Run...' hyperlink from the <B>Welcome</B> editor
+page. The test Eclipse instance that will appear should contain a tool bar
+button that will greet us with a 'Hello, World' message box when pressed. Our
+goal is to get our plug-in packaged, published and installed into another
+Eclipse so that we can see the same message box there.</P>
+<P>Before we move on to creating a feature, we must perform one important step:
+make sure all the files we need will end up in the packaged plug-in. An
+important file controls how plug-ins and features are built: build.properties.
+It has been created by PDE wizard automatically, but it may not contain all the
+things we need. In our particular case, 'Hello, World' wizard created
+<B>'</B>icons<B>'</B> directory that we need to include in the <FONT size=2>
+<IMG
+src="images/tag_1.gif" align=middle width="24" height="13"> </FONT>bin.includes
+variable as follows:</P><FONT size=2>
+<BLOCKQUOTE><PRE>bin.includes = plugin.xml,\<BR> xyz.jar,\<BR> <IMG src="images/tag_1.gif" align=middle width="24" height="13"> icons/<BR>source.xyz.jar = src/</PRE></BLOCKQUOTE></FONT>
+<P>Once we have the plug-in, know that it is working and ready to build, we will
+create a feature. To do so, select <B>New>Project>Plug-in
+Development>Feature Project</B>. We will use the same ID as for the plug-in
+but change the project name to avoid name collision in the workspace. We will
+choose 'com.example.xyz-feature'. After pressing <B>Next</B>, we will be able to
+change the ID into 'com.example.xyz', name into 'XYZ Feature' and provider into
+'XYZ Inc'. Pressing <B>Next</B> again will take us to the page where we can pick
+plug-ins and fragments that should belong to the feature. We will select the
+only plug-in available (com.example.xyz). At this point we can press
+<B>Finish</B> to get our project created.</P>
+<P>The wizard operation is analogous to the one for plug-in projects in that it
+creates the project and the necessary files, and opens the feature manifest for
+editing. The manifest editor is the usual PDE variety which means that you don't
+need to know the exact XML DTD to be productive - you can use form pages
+exclusively.</P>
+<P>Feature manifests can get complex in some cases, but we don't need to use all
+their capabilities for our little exercise. Our goal is to define the
+following:</P>
+<UL>
+ <LI>Feature id, version, name and provider (<B>Overview</B> page - already set
+ by the wizard)
+ <LI>Short description, license agreement, copyright notice (<B>Information</B>
+ page)
+ <LI>Plug-ins and fragments that belong to the feature (<B>Content</B> page -
+ already set by the wizard) </LI></UL>
+<P><IMG src="images/tryit.gif" width="61" height="13"> Switch to the Information
+page and<BR></P>
+<DIV style="MARGIN-LEFT: 40px">
+<UL>
+ <LI>select the <SPAN style="FONT-WEIGHT: bold">Feature Description</SPAN>
+ section and enter the following text: </LI></UL>
+<DIV style="MARGIN-LEFT: 40px"><SPAN style="FONT-STYLE: italic">This feature is
+designed to allow us to make XYZ plug-in available for installation using
+Eclipse Update Manager.</SPAN> </DIV>
+<DIV style="MARGIN-LEFT: 40px"><BR>
+ <IMG title="" alt="Feature Description"
+src="images/feature-desc.jpg" width="547" height="327"><BR><BR><B>Figure 1:</B>
+Setting the Feature Description </DIV></DIV>
+<DIV style="MARGIN-LEFT: 40px">
+<UL>
+ <LI>select the <SPAN style="FONT-WEIGHT: bold">Copyright Notice</SPAN> section
+ and enter the following text: </LI></UL>
+<DIV style="MARGIN-LEFT: 40px"><SPAN style="FONT-STYLE: italic">2003 XYZ Inc.
+All rights reserved.</SPAN></DIV>
+<DIV style="MARGIN-LEFT: 40px"><BR>
+ <IMG title="" alt="Feature Description"
+src="images/copyright.jpg" width="544" height="325"><BR><BR><B>Figure 2:</B>
+Setting the Copyright Notice </DIV></DIV>
+<DIV style="MARGIN-LEFT: 40px">
+<UL>
+ <LI>select the <SPAN style="FONT-WEIGHT: bold">License Agreement</SPAN>
+ section and enter the following text: </LI></UL>
+<DIV style="MARGIN-LEFT: 40px; FONT-STYLE: italic">License Agreement<BR><BR>You
+must accept this license agreement in order to install this<BR>feature into your
+product.</DIV>
+<DIV style="MARGIN-LEFT: 40px"><BR>
+ <IMG title="" alt="Feature Description"
+src="images/license.jpg" width="546" height="327"><BR><BR><B>Figure 3:</B> Setting
+the Licence Agreement</DIV></DIV>
+<P>Now save the file, switch to the <B>Overview</B> page and select
+<B>Preview</B> from the pop-up menu. This handy function taps into Eclipse
+Update API to test if the feature we are creating will be liked by Update
+Manager when packaged and deployed. If everything is fine, you should see the
+<B>Preview</B> (part of the Update Manager) open, showing you the feature
+properties. You should be able to see the description, follow the 'License' and
+'Copyright' hyperlinks and see the correct name, provider and version (and above
+all, this demonstrates that the manifest file is loaded without errors by the
+Update XML parser):</P>
+<P align=center>
+<IMG src="images/feature-preview.jpg"
+border=0 width="511" height="470"></P>
+<P align=center><B>Figure 4:</B> Preview of the feature as it is being designed
+in the workspace.</P>Note that the actual size and location of the view will
+depend on the perspective in which it was opened. We made the view in Figure 4
+taller to allow you to see it without the scroll bars. In most perspectives it
+opens stacked with the other views in the lower-right corner.<BR>
+<H3>Creating an update site</H3>
+<P>Having created a plug-in and a feature, we need to build them and make them
+available on an Eclipse <B>update site</B>. The update site concept is very
+powerful and flexible, but requires some advanced programming in order to tap
+into that power. For this reason, Eclipse provides a default implementation of
+the required interfaces that makes feature publishing easier and
+programming-free.</P>
+<P>We said earlier that in order to build a site, we need a <B>site map</B>
+(site.xml). In addition, we need to package features and plug-ins into JARs and
+place them alongside the map in the 'features' and 'plugins' directories,
+respectively. By placing these files and folders on an HTTP server connected to
+the Internet, you are making the site visible to Eclipse users around the
+world.</P>
+<P>There are many ways to build an update site. Large products with automated
+builds can package features and plug-ins, upload them onto the server and update
+site.xml automatically. For smaller projects and for experimentation, PDE
+provides tooling for update site creation. It will come in handy for our example
+as well.</P>
+<P><A name=siteLocation></A>We will start by creating an update site project by
+selecting <B>New>Project>Plug-in Development>Update Site Project</B>.
+We will pick 'update-site' for a project name, but choose a non-default location
+for the project for the following reasons:</P>
+<OL>
+ <LI>If your local machine is also a server or you have file system access to
+ the server (e.g. shared drives), you can create the site project directly in
+ the server root. Changes made to the server project resources will be
+ instantly visible to everybody.
+ <LI>Even if it isn't, by locating the update site outside of a workspace, you
+ can share the site between several workspaces. This is important if you want
+ to build <B>multiple versions</B> of features and plug-ins and place them in
+ the same site (which is often the case). You must do it this way because when
+ you are self-hosting in Eclipse, you can only work on one version of each
+ plug-in at a time per workspace. </LI></OL>
+<P>Very predictably, the wizard creates a new site project, site map and opens
+the file for editing in the usual PDE multi-page editor. </P>
+<P align=left>The first step is to connect the features in the workspace and our
+site. The update site manifest editor is actually a combination of an editor and
+a builder in that it keeps track of features in the workspace, builds them and
+packages them in a format required by the Update Manager. The packaged files are
+then placed directly into the site project in the required folders. To connect
+features and the site, we need to switch to the <B>Build</B> page and press
+<B>Add...</B> in <B>Features To Build</B> section. The wizard should contain
+'com.example.xyz' feature (version 1.0.0) that is in our workspace. When we
+choose it and press <B>Finish</B>, this feature project is now added to the
+build map of this site.</P>
+<P align=left>Adding a feature project to the build map will not make it visible
+to people that connect to our site. It is possible to have features in the
+update site that are not visible. For example, if you build a complex feature
+that includes several smaller ones, you only need to make the root visible in
+the site. When users select your complex feature for installation, all the
+children will be recursively downloaded as part of the process.</P>
+<P align=left>To make our XYZ feature visible, we need to select the checkbox in
+the above mentioned section. You will notice that an entry appeared in the
+<B>Outline</B> under <B>Features</B>. Indeed, if you switch to <B>Features</B>
+page, you will see this entry in the list. What this means is that the feature
+will be visible to users who connect to our site and browse it. Note how the
+feature archive name is a combination of the feature ID and version. This way
+you can place many different versions of the same feature side by side:</P>
+<P align=center>
+<IMG title="" alt="Features on update site"
+src="images/feature-refs.jpg" width="581" height="399"></P>
+<P align=center><B>Figure 5</B>: Defining the features that will be visible when
+connecting to the site.</P>
+<P align=left>Our site description is now ready to be built. To do so, we will
+switch to the <B>Build</B> page and press the <B>Build</B> button. After the
+build operation has finished, you should have a JAR in both the 'features' and
+'plugins' directory. Check that you have the following content in your Navigator
+or Package Explorer after the build operation. Note that Navigator shows all the
+resources, so you will also see a folder where build information is kept
+(.sitebuild). This folder is used by the site builder only and is hidden for a
+reason. It is used at development time only and plays no role in a published
+site.</P>
+<P align=center>
+<IMG src="images/explorer.jpg"
+border=0 width="235" height="192"></P>
+<P align=center><B>Figure 6</B>: Package Explorer view after building the update
+site.</P>
+<P align=center>
+<IMG src="images/tip.gif" align=left width="62" height="13"></P>
+<P align=left>You have probably noticed that there are two buttons in the
+<B>Build</B> page: <B>Build</B> and <B>Rebuild All</B>. Why two? The later is
+easy to understand: it unconditionally builds all the plug-ins and features in
+the build map. In contrast, the former builds only features and plug-ins that
+changed since the last build. Building features may take time if they reference
+many plug-ins, so it definitely makes life easier. However, it is not as
+fine-grain as incremental builders that run on resource changes, since the
+expectation is that you will not need them as often.</P>
+<H3 align=left>Testing the site</H3>
+<P align=left>We can test our site without leaving the workspace. Update Manager
+treats local and remote sites equally (the only exception being that remote
+sites have an extra download step before you can access its files). We can use
+this property to go to our site and verify that we can browse it correctly. If
+we can, so will our users once we publish it on the server.</P>
+<P align=left>All you need to do is open Update Manager (<B>Help>Software
+Updates>Update Manager</B>), locate icon <B>My Computer</B> in Feature
+Updates and drill down into the location on the file system where our
+'update-site' project folder is. You will notice that it is actually not
+represented as a folder in the view. Instead, it shows a pink diamond icon (<IMG
+title="" alt=site src="images/site_obj.gif" width="16" height="16">) used for
+update sites. This is a good sign - it means that the view recognized that this
+folder is in fact an update site and immediately switched into site browsing
+mode. You can browse the site right there, but a better way is to bookmark it
+(select it and choose <B>Bookmark Location...</B> from the pop-up menu). This
+will bookmark the site so that you don't have to drill down in the future.</P>
+<P align=left>If everything is OK, you should see <SPAN
+style="FONT-WEIGHT: bold">Other</SPAN> (the default category) with one feature
+in it: XYZ Feature 1.0.0. When you select it, the feature properties should show
+up in the <B>Preview</B>.</P>
+<P align=left>
+<IMG src="images/tip.gif" width="62" height="13"> When creating
+more complex sites, you would first create a <B>category definition</B> to help
+people accessing your site see features classified into logical groups. That
+way, categorized features will not appear under the Other folder, but under
+their category folder.</P>
+<P align=left>
+<IMG src="images/tip.gif" width="62" height="13"> As you are
+testing your site over and over, remember to select <B>Refresh</B> from the
+pop-up menu before making conclusions. Update Manager tries to be as efficient
+as possible so it will not react to changes in the file system unless you force
+it to drop the cached data and connect to the site anew.</P>
+<H3 align=left>Implanting the update URL</H3>
+<P align=left>There is one extra task we need to perform before publishing the
+site. It represents our investment in the future. Although our users can use
+Update Manager to navigate to the update site, find the new version and install
+it, it requires more knowledge and work than is really necessary. By implanting
+a URL that points at the update site, Eclipse can search for new updates
+automatically, with minimal user intervention.</P>
+<P align=left>Embedding a URL that points to the site with updates is easy, but
+you need to select the URL wisely. Once you ship the feature, the server must be
+located where you said it will be. You can change this URL in the subsequent
+versions of your feature, but do spend some time thinking about it - if you do,
+you will not need to change it often. For example, Eclipse.org update site is <A
+href="http://update.eclipse.org/updates/">http://update.eclipse.org/updates/</A>
+and is unchanged since release 2.0.</P>
+<P align=left>Since in our example the site is local on the file system, we will
+use file protocol for the update URL. All we need is to add the update URL to
+our feature.xml:</P>
+<DIV align=left>
+<P align=left>
+<IMG title="" alt="" src="images/tryit.gif" width="61" height="13">
+<BR>On the <B>Overview</B> page of the feature manifest editor locate the
+<B>Feature URLs</B> section. Choose <B>New>Update URL</B> from the pop-up
+menu and edit the object properties in the property sheet when created. /p>
+<P align=left>
+<IMG title="" alt="site url"
+src="images/url.jpg" width="716" height="422"><BR><B>Figure 7</B>: Setting the
+Update URL for a feature</P>
+<P>The URL path should match the directory where you defined your update site,
+so make sure you change the following URL if you copy/paste it:</P><PRE><FONT color=#008000 size=2>file:D:/eclipse-sdk2.1/eclipse/update-area/update-site/</FONT></PRE>
+<P>
+<IMG title="" alt=propsheet
+src="images/propsheet.jpg" width="379" height="165"></P><B>Figure 8</B>: Setting
+the Update URL in the property sheet
+<P></P></DIV>
+<H3 align=left>Publishing the site to a server</H3>
+<P align=left>
+<IMG src="images/tip.gif" width="62" height="13"> This step is not
+needed if you are directly updating a site on the local file system or on a
+local server, as it was discussed when <A
+href="#siteLocation">creating
+the update site project</A>.</P>
+<P align=left>You can publish the site in many ways. If you do not have access
+to a server, the simplest way to publish it is to export the site project into a
+local directory, outside the Eclipse workspace. </P>
+<P align=left>A more powerful way to publish the site to a remote server is by
+using the optional <B>Eclipse FTP and WebDAV Support</B> feature available as a
+separate download from Eclipse.org. You can create a target for your update site
+project on the server, and upload deltas using FTP or WebDAV protocols whenever
+you rebuild the site. If your server is not enabled for FTP or WebDAV, then
+you'll have to manually deploy the site to the server. In this example we assume
+that your server is FTP-ready.</P>
+<P align=left>First, let's use the Update Manager to download the FTP and WebDAV
+Support: switch to the Update Manager, add a bookmark to <A
+href="http://update.eclipse.org/updates/">http://update.eclipse.org/updates/</A>,
+expand it, expand <B>Eclipse SDK 2.1.0</B> category and find <B>Eclipse FTP and
+WebDAV Support</B>. Select the feature and press <B>Install Now</B> button in
+the <B>Preview</B>. It will download, install and configure this feature
+automatically. Restart when asked and that's it.</P>
+<P align=left>Now that our Eclipse workbench can act as an FTP client, we can
+prepare the site for publishing:</P>
+<OL>
+ <LI>Select the update site project and bring up the pop-up menu.
+ <LI>Choose '<SPAN style="FONT-WEIGHT: bold">Team->Target Site</SPAN>'. The
+ wizard will open.
+ <LI>Select '<SPAN style="FONT-WEIGHT: bold">FTP</SPAN>' protocol and press
+ 'Next'.
+ <LI>Select the FTP URL that includes the remote server and the path from the
+ FTP root to the physical root of the site as defined by the HTTP server.
+ <LI>Specify user name and password for the FTP account. Press Next.
+ <LI>Specify the directory that will be the project root on the server (use the
+ provided default that is the same as the project name).
+ <LI>Press 'Finish'. </LI></OL>
+<P>You have now established the target site. Changes you make in the workspace
+will be compared to the target and delta will be computed when upload is
+needed.</P>
+<P>To upload, select the project and use 'Team->Synchronize with target'
+option. This will bring the familiar 'Synchronize' view used with CVS
+repositories. Select the desired branch or the root and 'Upload' the content to
+the server.</P>
+<H3 align=left>The geek test</H3>
+<P align=left>Let's now pretend that our feature is published and that we were
+told that there is this cool XYZ feature that is a 'must have'. To pretend
+successfully, we need to install another copy of Eclipse 2.1.1 SDK in a
+different location (to act as a product) and launch it. When it comes up,
+immediately switch to the Update Manager and create a bookmark in Feature
+Updates. If the site was published locally, drill down to the site location
+using <B>My Computer</B> and create a bookmark for it. If the site was published
+on a remote server, then create a Site bookmark to the appropriate site URL.</P>
+<P align=left>You should be able to expand this bookmark and see the same things
+as before when we tested the site. This time, we will go all the way and press
+the <B>Install Now</B> button. You should accept our fake license, accept the
+default location and press <B>Finish</B>. After restarting Eclipse, our XYZ
+Feature (and XYZ Plug-in) will be installed.</P>
+<P align=left>How to tell that everything went well? Check any of the
+following:</P>
+<OL>
+ <LI>Switch to the <B>Resource</B> perspective and select <B>Window>Reset
+ Perspective</B> (this is required because perspective was created and
+ persisted before we installed our plug-in, so we must reset it to see our
+ contribution). A new tool bar button should show up, as well as <B>Sample
+ Menu</B> with a <B>Sample Action</B> in the menu bar. Both the button and the
+ action should open the 'Hello, World' message box, indicating that our plug-in
+ is alive and well.
+ <LI>Select <B>Help>About>Feature Details</B>. Our feature should be on
+ the list.
+ <LI>Switch to Update Manager and expand <B>Eclipse Platform</B> node in
+ <B>Install Configuration</B>. Expand the install location object. It should
+ show 'XYZ Feature 1.0.0'. </LI></OL>
+<H2>Providing feature updates</H2>
+<P>As it usually happens, after you successfully deploy the 1.0.0 version, it is
+likely you will need to provide bug fixes to your customers.</P>
+<P>One very important thing to remember is that once you publish your plug-ins
+and features, any changes to their code must cause version increments. After you
+change one line of your code, it starts to differ from what people have
+installed on their machines, which means it is not the same version. In Eclipse,
+this is handled by creating a maintenance branch in the repository. This branch
+is used for fixes of the shipped code base while further development goes on
+unimpeded in the main development stream.</P>
+<H3>Creating an update</H3>
+<P>Since we found a bug, we will create a <B>bug fix release</B>. We started
+with version 1.0.0, so we will make 1.0.1 this time (increment only service
+portion of the version). We need to make a number of changes to the existing
+plug-in and feature, so make sure the 1.0.0 versions are saved somewhere.</P>We
+will start by editing plugin.xml of our plug-in project and incrementing its
+version to 1.0.1. In addition, we will modify
+com.example.xyz.actions.SampleAction.java file to show a different text in the
+message box:
+<BLOCKQUOTE><PRE> <FONT color=#7f0055 size=2><B>public</B></FONT><FONT size=2> </FONT><FONT color=#7f0055 size=2><B>void</B></FONT><FONT size=2> run(IAction action) {<BR> MessageDialog.openInformation(<BR> window.getShell(),<BR> </FONT><FONT color=#2a00ff size=2>"Xyz Plug-in"</FONT><FONT size=2>,<BR> </FONT><FONT color=#2a00ff size=2>"Hello, UPDATED Eclipse world"</FONT><FONT size=2>);<BR> }</FONT></PRE></BLOCKQUOTE>
+<P>This will take care of the plug-in. Next, we will handle the feature. First,
+open feature.xml again. Since we changed plug-in version, we must repair the
+broken reference in the feature: on the <SPAN style="FONT-WEIGHT: bold">Content
+</SPAN>page remove the com.example.xyz plug-in and add it back (PDE will
+automatically handle this in a future Eclipse release). In addition, we must
+increment the feature version on the <SPAN style="FONT-WEIGHT: bold">Overview
+</SPAN>page to 1.0.1, because Update compares feature versions when scanning for
+new updates. Finally, we will change the description of the feature to say
+something about the fix; add this text to the Feature Description section: <SPAN
+style="FONT-STYLE: italic">This version contains a fix to a critical bug found
+during writing of this article</SPAN>.</P>
+<H3>Building and publishing the update</H3>
+<P>Now that we updated the feature, we must rebuild everything and
+republish.</P>
+<P>We will start by opening site.xml using the site map editor. When you switch
+to the <B>Build</B> page, note how the icon for the 'XYZ Feature 1.0.0' is gray
+and hollowed out. This indicates that we contain a reference to this feature but
+cannot find it in the workspace. This is OK - since this is shared project,
+there will always be features that we cannot find (because they are in other
+workspaces). We need to add our modified XYZ Feature 1.0.1 to this list and
+check the checkbox. This will add another feature entry to the site
+manifest.</P>
+<P>When we switch to the <B>Features</B> page, we can indeed see this entry.
+Repeating what we did before, we will select this entry and add it to our
+category. After saving the file, we can select <B>Build</B> from the pop-up menu
+(no need to switch back to the <B>Build</B> page). If everything went well, you
+should now have TWO plug-ins in the 'plugins' folder and TWO features in the
+'features' folder.</P>
+<P>As before, we can preview the site using Update Manager (this is where
+bookmarking the site is paying off). You should now see two features (XYZ
+Feature 1.0.0 and 1.0.1) and switching between them should show differences in
+the description.</P>
+<H3>The geek test, updated</H3>
+<P>Finally, the fix is ready. This is where our decision to implant a URL that
+points at our update site is paying off. All the users need to do is select
+<B>Help>Software Updates>New Updates</B> and wait for the results.</P>
+<P><IMG src="images/tryit.gif" width="61" height="13"> So far, our 'pretend'
+Eclipse product has 'XYZ Feature 1.0.0' installed. When we select this command,
+a progress monitor will show up, searching for new updates. It is shortly
+replaced with a wizard showing the results of the search:</P>
+<P align=center>
+<IMG src="images/one-click2.jpg"
+border=0 width="600" height="500"></P>
+<P align=center><B>Figure 9:</B> Result of the update search.</P>
+<P>What happened? Eclipse checked currently installed features, connected to the
+update sites using URLs in feature manifests, and searched for features with the
+same ID but higher version. Since our site had a feature that matched this
+description, it showed up in the wizard. We can now proceed with the
+installation and the result will be the same as if we installed it from the
+Update Manager, only with fewer mouse clicks.</P>
+<P>When you publish your features, you definitely want your users to follow this
+path because it is the most straightforward way of bringing the updates in.</P>
+<P>
+<IMG title="" alt="" src="images/tip.gif" width="62" height="13"> After
+installing a new feature or updating an existing feature it is possible to go
+back to a previous configuration state. Do this from the Configuration History
+node in the Install Configuration view.</P>
+<H2>Conclusion</H2>
+<P>We hope this article makes you think twice about sending more 'just unzip
+...' notes with attachments. Instead, your next note should read:</P>
+<BLOCKQUOTE style="FONT-STYLE: italic">
+ <P>A new tool named XYZ Feature is now available for download from update
+ site<BR>http://xyz.example.com/updates/</P></BLOCKQUOTE>
+<P>Each subsequent note should simply be:</P>
+<P><B> </B><SPAN
+style="FONT-STYLE: italic">Version 1.0.1 of XYZ Feature is now available for
+download from update site</SPAN><BR style="FONT-STYLE: italic"><SPAN
+style="FONT-STYLE: italic">
+http://xyz.example.com/updates/ </SPAN><BR style="FONT-STYLE: italic"><SPAN
+style="FONT-STYLE: italic"> You can
+install it directly by selecting the New Updates
+action.</SPAN><B><BR></B> <BR>More can be
+done with Eclipse update. You can make a more complex feature by <SPAN
+style="FONT-WEIGHT: bold">including </SPAN>several smaller ones, with some of
+them <SPAN style="FONT-WEIGHT: bold">optional</SPAN>. By providing <SPAN
+style="FONT-WEIGHT: bold">patches</SPAN>, you can update branches of the complex
+feature hierarchy, not just the root feature. You can also create a
+<B>branding</B> plug-in and associate it with a feature to make your feature
+stand out in a number of places in the workbench. If your feature is <SPAN
+style="FONT-WEIGHT: bold">primary</SPAN>, that plug-in can also contain a splash
+screen that replaces the default Eclipse splash. Finally, you can package a set
+of features and plug-ins that represent a significant function and add it to
+other Eclipse products during installation using <B>linked extensions</B>.</P>
+<P>Our example only scratched the surface of update capabilities. As your code
+grows in complexity, so will your software update needs.</P>
+<h2> </h2>
+<h2>Appendix: Update Manager Developer Tips</h2>
+<p><b>By Alexandre Junqueira, INMETRICS</b> <br>
+ <font size="-1">January 13, 2004</font> </p>
+<P>This appendix presents some real-world tips to avoid common mistakes during
+ the creation and maintenance of Eclipse update sites. Creating an update-site
+ is easy, but you need to adhere to some unwritten rules to get a well-functioning
+ artifact.</P>
+<h3>Tip #1: Always remember trailing slash "/"</h3>
+<p>One major pitfall when build Update
+sites is that everything goes well until the final test. But then, even the most
+simplistic site <b>doesn't work</b> in Update Manager (or Install/Update dialog
+-- for those using Eclipse 3.0). </p>
+<p>Then comes the "bit-brushing" work of
+trying to get everything work by hand, since the "update site" is no more than a
+bunch of XML and JAR files you've created with assistance of Eclipse wizards ...
+</p>
+<ol>
+ <li>
+ <p>first, you try to check the HTTP
+ access to the update site, and it works; </li>
+ <li>
+ <p>then, you check file permissions to
+ certifies that anyone can read them; they're also ok; </li>
+ <li>
+ <p>come back to the Eclipse workbench
+ and, surprisingly, it <b>doesn't work at all</b>; </li>
+</ol>
+<p>You check, double-check, and even
+triple-check the above steps, and then you give up on creating an update site
+and deliver your brand new plug-in as a downloadable .zip file to the community,
+so at least it could be <b>manually</b> installed. </p>
+<p>This situation is common place for
+you? If so, then you've probably ran in one of the most tricky behaviors of the
+update manager. </p>
+<p>The problem is: <b>you must put a
+trailing slash ("/") in the update site URL defined in "feature.xml" XML file.</b>
+</p>
+<p>Go back to the Feature Editor (if
+you're using Eclipse 3.x), or open "feature.xml" file you've created. Look for
+the <b><url></b> tag. </p>
+<p>This tag contains the reference to
+the site where Update Manager will look for your plug-ins installation files.
+BUT THIS URL MUST BE TERMINATED BY A SLASH CHARACTER. </p>
+<p>Why such behavior? Because Eclipse's
+Update Manager appends plug-in distribution file name to the URL you've set up
+there, <b>without</b> pre-pending with "/" ... so, instead of getting something
+like </p>
+<pre>"http://your.site/update/plugin_1.0.0.jar"</pre>
+<p>it gets </p>
+<pre>"http://your.site/updateplugin_1.0.0.jar"</pre>
+<p>which explains why, after all, Eclipse doesn't find your master piece. It's
+looking for an inexistent URL!</p>
+<h3>Tip #2: Fill the blanks</h3>
+<p>Another common pitfall when building
+features to publish in update sites is to skip writing copyright and license
+notices. It's especially true when building
+your update site for the first time (you don't want to write a major legal act;
+you're just trying to make your work available, no?). But Eclipse's Update Manager will
+look for such disclaimers and doesn't allow you to install features that don't
+provide such notices.
+So, to avoid such pain, write down at least a simple word in both fields.</p>
+<p>The recommended way is to use a
+template-based text for both fields, such as: </p>
+<dl>
+ <dt><b>copyright</b> </dt>
+ <dd>Copyright (c) 2004 by John Doe. All rights reserved </dd>
+ <dt><b>legal</b> </dt>
+ <dd>This work follows CPL/GPL/LGPL/BSD licensing schema. See
+ <license-site> for more details
+ about usage and distribution. </dd>
+</dl>
+<h3>Tip #3: Be careful when using <i>build.xml</i></h3>
+<p>If you're the
+developer of the plug-in being published, then you've almost certainly created
+the <b>build.xml</b> using the "Create build file" (or "Create ant build file")
+pop-up menu option on plugin.xml. If you did so, and
+especially if you've customized the file, then BE CAREFUL. Before creating and
+building an update site project, create a backup of your <b>build.xml</b> file.
+The update-site project build option will <b>erase</b> every <i>build.xml</i> it
+finds in the features and plugins required by the site which leads to lost
+work. </p>
+<p>To avoid this
+problem, create another ant build-file to hold your customization and use it
+instead of default the "build.xml".</p></div>
+
+<div class="notices"><p>Java and all Java-based trademarks and logos are trademarks or
+registered trademarks of Sun Microsystems, Inc. in the United States, other
+countries, or both.</p>
+</div>
+</body></html>
\ No newline at end of file
diff --git a/Article-Update/info.xml b/Article-Update/info.xml
new file mode 100644
index 0000000..ca26a18
--- /dev/null
+++ b/Article-Update/info.xml
@@ -0,0 +1,6 @@
+<article>
+ <bug id="242935"/>
+ <project id="eclipse">
+ <release>2.1</release>
+ </project>
+</article>
\ No newline at end of file
