{section}
{column}
This page explains how you can update Petals Studio and install new Software on it.
To ease the comprehension of the update mechanism, it first introduces the basics of the studio's assembly process.
It is only then that the concrete update mechanism is explained and shown.
{column}
{column:width=350px}
{panel:title=Table of contents}{toc}{panel}
{column}
{section}
h1. Eclipse builds and updates
Petals Studio us built upon Eclipse.
For the curious, Petals Studio is in fact an Eclipse RCP (Rich Client Platform).
It matters because it allows to understand how it is built, how you can update it or install new tools in the studio.
h2. Plug-ins and Features
Petals Studio is a set of Eclipse *plug-ins*, grouped together as a set of *features* and distributed through a *product*.
Each plug-in being an OSGi bundle, it has a version, exports and requires packages, and expresses dependencies towards other plug-ins.
\\
Thus, Petals Studio defines some features made-up of determined plug-ins:
* _The Petals Basis feature_ contains all the plug-ins for Java, XML, CVS support, the framework core, etc...
* _The Petals Core feature_ contains the main Petals plug-ins.
* _The Petals SCA feature_ contains the Petals SCA plug-ins.
* _The Petals BPEL feature_ contains the Petals BPEL plug-ins.
A feature defines a group of plug-ins.
*When you install a feature, you install all of its plug-ins. Same thing if you uninstall it or update it.*
Generally, plug-ins are associated together in a feature because they have dependency relations or provide complementary features (for a user).
\\
In the same time, there is *the management of plug-ins dependencies*.
Indeed, a plug-in may need other plug-ins to be installed to work. And a plug-in may be required by other plug-ins as well.
Plug-ins dependencies may involve only the plug-in ID or the plug-in ID and version ranges (e.g. version 1.0.2, any version between 1.0 and 1.1 and so on).
\\
To illustrate these facts, let's get back to the way the studio is built:
* The _Petals BPEL feature_ contains the plug-ins for the BPEL Designer, as well as the Petals plug-in to create a new BPEL project and validate a BPEL with the Petals BPEL Validator.
* However, some of these plug-ins depend on plug-ins located in the _Petals Core feature_. The features define a functional package. But *plug-in dependencies can break feature definition*.
\\
Petals Studio embeds about several hundreds of plug-ins. An Eclipse installation may count much more plug-ins.
When you install or update plug-ins, the Eclipse installer must check the coherence of what is installed with what is about to be installed.
If the new elements to install miss a dependency, or if they break a dependency relation, then the update or installation will fail.
h2. p2
To make things work and easy for the user, the Eclipse Foundation developed a tool called *p2* and in charge of provisioning an Eclipse platform.
This tool in fact works at the bundle level and is associated with the OSGi runtime Equinox (used and embedded in Eclipse and in the studio).
\\
When you install or update your studio, p2 builds a graph dependency and resolve conflicts when it is possible.
It is also capable of downloading missing dependencies automatically. To do so, it needs to know Eclipse repositories. That is to say locations where Eclipse plug-ins are available. Generally, these dependencies should all be available on the same repository (also called _update site_).
\\
{note}
Unlike Maven repositories, the concept of _snapshot_ does not exist for Eclipse repositories.
{note}
\\
Consequently, if you are signaled an error in the studio while installing a new feature and that a dependency is said missing, you will need to install it first.
Also, *remember that p2 does not install single plug-ins, but the features that contain these plug-ins*.
The constraints are on the entire package and not just on the plug-ins.
h1. Installing new software
It is possible to install new plug-ins in the Petals Studio.
However, *it is essential that these plug-ins are not part of the native package*.
That is to say they were not already installed in the studio when you downloaded it.
If they were already installed, then check [the section about native plug-ins|#NativePlugIns].
\\
Click *Help > Install New Software...*. A dialog shows up.
!PetalsStudio_Updating_1.jpg!
\\
Select the update site location in the drop-down menu.
This is the repository from which the plug-ins will be downloaded and installed.
If your update site does not appear in the list, click *Add...*.
Give it a *name* and specify the *location* (as an URL). Then, click *OK*.
\\
When a repository is selected in the menu, the available features are listed in the box below.
Select the features you need and click *Next*.
!PetalsStudio_Updating_2.jpg!
{note}
If you do not see any category or feature, try to uncheck *Group items by category*.
{note}
\\
Once you have clicked *Next*, p2 computes the list of dependencies and determines the features to install.
If a dependency could not be found (in this repository) or breaks dependency constraints, an error is shown.
If the install request is possible, the next page shows the list of features to install. In this case, you can click *Next*.
!PetalsStudio_Updating_3.jpg!
\\
The next page shows you the license of every element to install.
It is up to you to decide whether you accept them or not. Be careful, the agreement involves the whole install package.
!PetalsStudio_Updating_4.jpg!
\\
Then you can click *Finish*. The installation process can begin.
!PetalsStudio_Updating_5bis.jpg!
{note}
Sometimes, timeout may occur during an update.
If it happens, run the update manager once again.
{note}
\\
Once this is done, you are asked to restart your platform to make your changes effective.
Although it is not mandatory to restart, it is better to restart anyway.
Indeed, some plug-ins may need to execute some actions at startup to work. It is for these plug-ins you should restart.
!PetalsStudio_Updating_6.jpg!
h1. {anchor:NativePlugIns} Updating native plug-ins
{note}
This is only possible from the version 1.1 of the studio.
People working with Petals Studio 1.0 have to install a more recent of the version to be able to update native plug-ins.
{note}
When you install your studio, there are two repositories that are already registered.
Once of them points to a repository hosted by Petals Link and on which we publish product updates.
Product updates only concern version whose third digit has changed (e.g. 1.1.0 to 1.1.1).
\\
To check updates for the native plug-ins, select *Help > Check for Updates*.
If there is nothing to update, an information dialog appears.
Otherwise, an update dialog appears, listing all the new features available.
The update wizard is then very similar to the one described previously.
{column}
This page explains how you can update Petals Studio and install new Software on it.
To ease the comprehension of the update mechanism, it first introduces the basics of the studio's assembly process.
It is only then that the concrete update mechanism is explained and shown.
{column}
{column:width=350px}
{panel:title=Table of contents}{toc}{panel}
{column}
{section}
h1. Eclipse builds and updates
Petals Studio us built upon Eclipse.
For the curious, Petals Studio is in fact an Eclipse RCP (Rich Client Platform).
It matters because it allows to understand how it is built, how you can update it or install new tools in the studio.
h2. Plug-ins and Features
Petals Studio is a set of Eclipse *plug-ins*, grouped together as a set of *features* and distributed through a *product*.
Each plug-in being an OSGi bundle, it has a version, exports and requires packages, and expresses dependencies towards other plug-ins.
\\
Thus, Petals Studio defines some features made-up of determined plug-ins:
* _The Petals Basis feature_ contains all the plug-ins for Java, XML, CVS support, the framework core, etc...
* _The Petals Core feature_ contains the main Petals plug-ins.
* _The Petals SCA feature_ contains the Petals SCA plug-ins.
* _The Petals BPEL feature_ contains the Petals BPEL plug-ins.
A feature defines a group of plug-ins.
*When you install a feature, you install all of its plug-ins. Same thing if you uninstall it or update it.*
Generally, plug-ins are associated together in a feature because they have dependency relations or provide complementary features (for a user).
\\
In the same time, there is *the management of plug-ins dependencies*.
Indeed, a plug-in may need other plug-ins to be installed to work. And a plug-in may be required by other plug-ins as well.
Plug-ins dependencies may involve only the plug-in ID or the plug-in ID and version ranges (e.g. version 1.0.2, any version between 1.0 and 1.1 and so on).
\\
To illustrate these facts, let's get back to the way the studio is built:
* The _Petals BPEL feature_ contains the plug-ins for the BPEL Designer, as well as the Petals plug-in to create a new BPEL project and validate a BPEL with the Petals BPEL Validator.
* However, some of these plug-ins depend on plug-ins located in the _Petals Core feature_. The features define a functional package. But *plug-in dependencies can break feature definition*.
\\
Petals Studio embeds about several hundreds of plug-ins. An Eclipse installation may count much more plug-ins.
When you install or update plug-ins, the Eclipse installer must check the coherence of what is installed with what is about to be installed.
If the new elements to install miss a dependency, or if they break a dependency relation, then the update or installation will fail.
h2. p2
To make things work and easy for the user, the Eclipse Foundation developed a tool called *p2* and in charge of provisioning an Eclipse platform.
This tool in fact works at the bundle level and is associated with the OSGi runtime Equinox (used and embedded in Eclipse and in the studio).
\\
When you install or update your studio, p2 builds a graph dependency and resolve conflicts when it is possible.
It is also capable of downloading missing dependencies automatically. To do so, it needs to know Eclipse repositories. That is to say locations where Eclipse plug-ins are available. Generally, these dependencies should all be available on the same repository (also called _update site_).
\\
{note}
Unlike Maven repositories, the concept of _snapshot_ does not exist for Eclipse repositories.
{note}
\\
Consequently, if you are signaled an error in the studio while installing a new feature and that a dependency is said missing, you will need to install it first.
Also, *remember that p2 does not install single plug-ins, but the features that contain these plug-ins*.
The constraints are on the entire package and not just on the plug-ins.
h1. Installing new software
It is possible to install new plug-ins in the Petals Studio.
However, *it is essential that these plug-ins are not part of the native package*.
That is to say they were not already installed in the studio when you downloaded it.
If they were already installed, then check [the section about native plug-ins|#NativePlugIns].
\\
Click *Help > Install New Software...*. A dialog shows up.
!PetalsStudio_Updating_1.jpg!
\\
Select the update site location in the drop-down menu.
This is the repository from which the plug-ins will be downloaded and installed.
If your update site does not appear in the list, click *Add...*.
Give it a *name* and specify the *location* (as an URL). Then, click *OK*.
\\
When a repository is selected in the menu, the available features are listed in the box below.
Select the features you need and click *Next*.
!PetalsStudio_Updating_2.jpg!
{note}
If you do not see any category or feature, try to uncheck *Group items by category*.
{note}
\\
Once you have clicked *Next*, p2 computes the list of dependencies and determines the features to install.
If a dependency could not be found (in this repository) or breaks dependency constraints, an error is shown.
If the install request is possible, the next page shows the list of features to install. In this case, you can click *Next*.
!PetalsStudio_Updating_3.jpg!
\\
The next page shows you the license of every element to install.
It is up to you to decide whether you accept them or not. Be careful, the agreement involves the whole install package.
!PetalsStudio_Updating_4.jpg!
\\
Then you can click *Finish*. The installation process can begin.
!PetalsStudio_Updating_5bis.jpg!
{note}
Sometimes, timeout may occur during an update.
If it happens, run the update manager once again.
{note}
\\
Once this is done, you are asked to restart your platform to make your changes effective.
Although it is not mandatory to restart, it is better to restart anyway.
Indeed, some plug-ins may need to execute some actions at startup to work. It is for these plug-ins you should restart.
!PetalsStudio_Updating_6.jpg!
h1. {anchor:NativePlugIns} Updating native plug-ins
{note}
This is only possible from the version 1.1 of the studio.
People working with Petals Studio 1.0 have to install a more recent of the version to be able to update native plug-ins.
{note}
When you install your studio, there are two repositories that are already registered.
Once of them points to a repository hosted by Petals Link and on which we publish product updates.
Product updates only concern version whose third digit has changed (e.g. 1.1.0 to 1.1.1).
\\
To check updates for the native plug-ins, select *Help > Check for Updates*.
If there is nothing to update, an information dialog appears.
Otherwise, an update dialog appears, listing all the new features available.
The update wizard is then very similar to the one described previously.