Jump to: navigation, search

Difference between revisions of "Equinox/p2/Helios Migration Guide"

< Equinox‎ | p2
(CapabilityQuery)
 
(3 intermediate revisions by 2 users not shown)
Line 7: Line 7:
 
In the [[Ganymede]] and [[Galileo]] releases, p2 services were registered as global OSGi services. This style made it difficult to support multiple instances of p2 services operating in the same framework instance at the same time. The p2 API now uses an approach where services are obtained from a provisioning agent instance rather than directly from the OSGi registry. This means code like this:
 
In the [[Ganymede]] and [[Galileo]] releases, p2 services were registered as global OSGi services. This style made it difficult to support multiple instances of p2 services operating in the same framework instance at the same time. The p2 API now uses an approach where services are obtained from a provisioning agent instance rather than directly from the OSGi registry. This means code like this:
  
 +
<source lang="java">
 
   ServiceReference ref = bundleContext.getServiceReference(IEngine.class.getName());
 
   ServiceReference ref = bundleContext.getServiceReference(IEngine.class.getName());
 
   IEngine engine = (IEngine)bundleContext.getService(ref);
 
   IEngine engine = (IEngine)bundleContext.getService(ref);
 +
</source>
  
 
Is now replaced by code like this:
 
Is now replaced by code like this:
  
 +
<source lang="java">
 
   IProvisioningAgent agent = ...;//get the agent you want to work with
 
   IProvisioningAgent agent = ...;//get the agent you want to work with
 
   IEngine engine = (IEngine) agent.getService(IEngine.SERVICE_NAME);
 
   IEngine engine = (IEngine) agent.getService(IEngine.SERVICE_NAME);
 +
</source>
 
    
 
    
 
For details on how to obtain an agent, see the [[Equinox/p2/Multiple_Agents#Using_the_agent_API|Multiple Agents]] documentation.
 
For details on how to obtain an agent, see the [[Equinox/p2/Multiple_Agents#Using_the_agent_API|Multiple Agents]] documentation.
 +
 +
===Default Agent and Declarative Services===
 +
IProvisioningAgent and related services for the currently running system (see [[Equinox/p2/Multiple_Agents#Using_the_agent_API|Multiple Agents]]) are registered with declarative services (DS).  If you want to take advantage of these (and not register them yourself), you must include the declarative services bundle ('''org.eclipse.equinox.ds''') in your target platform and make sure it activates.
  
 
= Metadata changes =
 
= Metadata changes =
Line 45: Line 52:
 
Or, using Java 5 generics:
 
Or, using Java 5 generics:
  
  IRequirement cap = ...;
+
<source lang="java">
  new ExpressionQuery<IInstallableUnit>(IInstallableUnit.class,  
+
IRequirement cap = ...;
 +
new ExpressionQuery<IInstallableUnit>(IInstallableUnit.class,  
 
cap.getMatches());
 
cap.getMatches());
 +
</source>
  
 
== InstallableUnitQuery ==
 
== InstallableUnitQuery ==
Line 57: Line 66:
 
There is currently no direct API replacement for IUPropertyQuery, but the equivalent query can be performed using an expression query:
 
There is currently no direct API replacement for IUPropertyQuery, but the equivalent query can be performed using an expression query:
  
  new ExpressionQuery<IInstallableUnit>(IInstallableUnit.class,
+
<source lang="java">
    ExpressionUtil.parse("properties[$0] == $1"), "foo", "true");
+
new ExpressionQuery<IInstallableUnit>(IInstallableUnit.class,
 +
ExpressionUtil.parse("properties[$0] == $1"), "foo", "true");
 +
</source>
  
 
The above will match all IInstallableUnits with a "foo" property whose value is "true".
 
The above will match all IInstallableUnits with a "foo" property whose value is "true".
Line 68: Line 79:
 
The previous provisional engine API required the client to construct Operand instances to be passed into the engine. Rather than constructing operands, the client now constructs a plan object that is passed into the engine. For example, a client that previously created an InstallableUnitOperand and passed it to IEngine#perform would now do the following:
 
The previous provisional engine API required the client to construct Operand instances to be passed into the engine. Rather than constructing operands, the client now constructs a plan object that is passed into the engine. For example, a client that previously created an InstallableUnitOperand and passed it to IEngine#perform would now do the following:
  
  IEngine engine = ...;
+
<source lang="java">
  IProvisioningPlan plan = engine.createPlan(profile, context);
+
IEngine engine = ...;
  plan.addInstallableUnit(someIU);
+
IProvisioningPlan plan = engine.createPlan(profile, context);
  engine.perform(plan, phases, monitor);
+
plan.addInstallableUnit(someIU);
 +
engine.perform(plan, phases, monitor);
 +
</source>
  
[[Category:Equinox p2]]
+
[[Category:Equinox p2|Helios Migration Guide]]

Latest revision as of 14:30, 21 June 2010

In the Helios release p2 graduated much of its provisional API into stable, real API. This page provides some guidance to users of the old provisional p2 API on how to migrate to the mature API in the Helios release.

Pervasive changes

Switch from global OSGi services to agent-specific services

In the Ganymede and Galileo releases, p2 services were registered as global OSGi services. This style made it difficult to support multiple instances of p2 services operating in the same framework instance at the same time. The p2 API now uses an approach where services are obtained from a provisioning agent instance rather than directly from the OSGi registry. This means code like this:

  ServiceReference ref = bundleContext.getServiceReference(IEngine.class.getName());
  IEngine engine = (IEngine)bundleContext.getService(ref);

Is now replaced by code like this:

  IProvisioningAgent agent = ...;//get the agent you want to work with
  IEngine engine = (IEngine) agent.getService(IEngine.SERVICE_NAME);

For details on how to obtain an agent, see the Multiple Agents documentation.

Default Agent and Declarative Services

IProvisioningAgent and related services for the currently running system (see Multiple Agents) are registered with declarative services (DS). If you want to take advantage of these (and not register them yourself), you must include the declarative services bundle (org.eclipse.equinox.ds) in your target platform and make sure it activates.

Metadata changes

IRequiredCapability

IRequiredCapability was limiting in what it could express. For example it could not express negation and or'ing, and it could only described dependencies on something that had a namespace, a name and a version and we are striving to express requirements and capabilities on other things (for example BundleExecutionEnvironment). As such, to ensure for API evolution we have turned the too specific IRequiredCapability into an IRequirement.

IInstallableUnit

IInstallableUnit use to have constants allowing for the identification of groups, categories and the like. These constants were either used to query for a given kind of element in a repository or identify the kind of a given element. The constants have been removed from the API to the benefit of pre-canned queries and helper methods (e.g GroupQuery and CategoryQuery)

Query changes

CapabilityQuery

CapabilityQuery from the provisional API has been deleted in favor of expressions. Thus the former:

IRequiredCapability cap = ...;
new CapabilityQuery(cap);

Can be written as:

IRequirement cap = ...;
new ExpressionQuery(IInstallableUnit.class, cap.getMatches());

Or, using Java 5 generics:

IRequirement cap = ...;
new ExpressionQuery<IInstallableUnit>(IInstallableUnit.class, 
cap.getMatches());

InstallableUnitQuery

This class has been replaced by factory methods on the QueryUtil class. See QueryUtil#createIUQuery(...).

IUPropertyQuery

There is currently no direct API replacement for IUPropertyQuery, but the equivalent query can be performed using an expression query:

new ExpressionQuery<IInstallableUnit>(IInstallableUnit.class,
 ExpressionUtil.parse("properties[$0] == $1"), "foo", "true");

The above will match all IInstallableUnits with a "foo" property whose value is "true".

Engine changes

Operands

The previous provisional engine API required the client to construct Operand instances to be passed into the engine. Rather than constructing operands, the client now constructs a plan object that is passed into the engine. For example, a client that previously created an InstallableUnitOperand and passed it to IEngine#perform would now do the following:

IEngine engine = ...;
IProvisioningPlan plan = engine.createPlan(profile, context);
plan.addInstallableUnit(someIU);
engine.perform(plan, phases, monitor);