modules/ROOT/pages/modules/applications.mdtext - aries-antora-site - Git at Google

 Title: Applications
 <a name="Applications-AriesApplications"></a>
 # Aries Applications

 An Aries application is a collection of one or more OSGi modules that
 together provide a coherent business function. An Aries application can
 consist of modules of many different types.  For example, a Aries
 application providing Web banking might consist of bundles with Web content
 (Web Application Bundles), bundles with Blueprint contexts, and bundles
 with JPA entities and persistence configuration (Persistence Bundles).

 An Aries application isolates the OSGi services offered by its contained
 modules so that they are not visible outside the application unless
 explicitly configured to be exported from the application. Aries
 applications have several ways of accepting workloads: an Aries
 applications may include Web bundles for processing HTTP workloads; it may
 export one or more of the services offered by its contained modules to
 other Aries applications or for distribution as a Web service.

 With the isolation runtime, each Aries application runs in its own isolated
 OSGi framework instance with its own OSGi service registry. Bundles in one
 Aries application cannot see bundles, services, or packages that are
 defined in another OSGi application, unless the bundles, services, or
 packages are explicitly shared by both applications. An Aries application
 can also load packages and consume OSGi services from a shared bundle
 space, that is, the OSGi framework instance that is the parent of all the
 isolated framework instances of the OSGi applications.

 <a name="Applications-StructureofanAriesapplication"></a>
 ## Structure of an Aries application

 An Aries application is packaged as a zip file with a '.eba' suffix. Its
 structure is as follows:

 <DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Sample Aries application structure</B></DIV><DIV class="codeContent panelContent">
     META-INF/APPLICATION.MF<br>
     bundle1.jar<br>
     bundle2.jar<br>
     bundle3.jar<br>
 </DIV>
 </DIV>

 The file must contain either an APPLICATION.MF with at least one bundle
 listed in its Application-Content header (see below), or at least one
 bundle 'by value' within the .eba. No 'by value' bundles are required if a
 valid APPLICATION.MF is present.

 Application metadata, APPLICATION.MF,  stored in the .eba file defines the
 isolation scope of the bundles that the OSGi application uses. An Aries
 applicaiton can also use metadata to permit some of its constituent bundles
 to be shared. Sharing in this way can reduce the memory and resource
 requirements of a system. Shared bundles must be provided by reference
 rather than contained directly in an application.

 <a name="Applications-AriesApplicationManifest"></a>
 ## Aries Application Manifest

 An Aries Application is defined using a Manifest. The Aries manifest is
 located at META-INF/APPLICATION.MF and describes modularity at the
 application level. The manifest enumerates the modules that comprise the
 Aries application along with any OSGi services exported from, or referenced
 by, those modules.  The following is an example of an Aries manifest:

 <DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>APPLICATION.MF</B></DIV><DIV class="codeContent panelContent">
     Manifest-Version: 1.0<br>
     Application-ManifestVersion: 1.0<br>
     Application-Name: Bank Account<br>
     Application-SymbolicName: com.mybank.account.app<br>
     Application-Version: 1.0<br>
     Application-Content: <br>
     	com.mybank.account.bankWeb; version=1.0.0,<br>
     	com.mybank.account.bankAccount; version=1.0.0,<br>
     	com.mybank.account.common; version=1.0.0,<br>
     	com.mybank.account.utility; version=1.0.0<br>
     Use-Bundle: com.mybank.account.admin;version="[1.0.0,2.0.0)"<br>
     Application-ExportService: com.mybank.account.service.AccountService<br>
     Application-ImportService:<br>
 com.mybank.security.UserAuthService;filter="(security=strong)"<br>
 </DIV>
 </DIV>

 The manifest headers are as follows:

 * Manifest-Version - a version number for the manifest format.
 * Application-ManifestVersion - identifies the application manifest version
 to which this manifest conforms
 * Application-Name - a human readable name for the application
 * Application-SymbolicName - a name to uniquely identify the application.
 Follows the same scheme as Bundle-SymbolicName.
 * Application-Version - uniquely identify the version of the application.
 The combination of symbolic name and version must be unique within an Aries
 application runtime.
 * Application-Content - a list of 'root' bundles to provision for the
 application. 'Version' identifies a version range for the bundle to be
 provisioned thus allowing flexibility. The version format is identical to
 that used for OSGi import (e.g. Import-Package).
 * Use-Bundle - a list of bundles bundles to use to satisfy the package
 dependencies of bundles in the Application-Content list. Each bundle in the
 Use-Bundle list must provide at least one package to at least one bundle in
 the Application-Content list. These bundles will be provisioned into the
 shared bundle space at run time.
 * Application-ExportService - a list of service interface names and
 optional filters identifying services provided by the application which can
 be accessed outside the application.
 * Application-ImportService - a list of service interface names and
 optional filters identifying services which the application would like to
 consume from outside the application.

 Often, you do not require a Use-Bundle header, but there are some
 situations where it is useful. You can use it to restrict the level at
 which sharing is possible. For example, you can ensure that an application
 uses the same bundle for package imports that it was tested with.
 Alternatively, you can ensure that two applications use the same bundle for
 package imports. By setting the restriction at application level, the
 bundle can remain flexible.

 <a name="Applications-AriesDeploymentManifest"></a>
 ## Aries Deployment Manifest

 The Aries application model allows for the possibility that the bundles
 listed in APPLICATION.MF's Application-Content header, plus those
 optionally included within a .eba file, may have unsatisfied package or
 service dependencies. Such missing dependencies may be obtained
 ('provisioned') from one or more bundle repositories. Aries will provide a
 generic 'Resolver' API which may be backed by technology such as [Felix OBR](http://felix.apache.org/site/apache-felix-osgi-bundle-repository.html)
  or [Equinox p2|http://wiki.eclipse.org/Equinox_p2_Getting_Started]
 . Although it is possible to re-resolve an application every time it is
 installed, or even started, this may result in inconsistent behaviour as
 the contents of an associated bundle repository changes. Aries uses a
 second file, META-INF/DEPLOYMENT.MF to record a single consistent set of
 bundles that fully satisfy an application's dependencies. The bundles
 recorded in DEPLOYMENT.MF will be loaded into the runtime each time the
 application is installed. A DEPLOYMENT.MF file will be generated if one
 does not exist, or honoured if provided. Here's an example:

 <DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>DEPLOYMENT.MF</B></DIV><DIV class="codeContent panelContent">
     Manifest-Version: 1.0<br>
     Application-Version: 1.0<br>
     Application-SymbolicName: com.mybank.account.app<br>
     Deployed-Content: com.mybank.account.bankWeb; deployed-version=1.0.0,<br>
     	com.mybank.account.bankAccount; deployed-version=1.0.0,<br>
     	com.mybank.account.common; deployed-version=1.2.0,<br>
     	com.mybank.account.utility; deployed-version=1.0.0, <br>
     	com.mybank.utils.logging; deployed-version=1.3.1<br>
     Provision-Bundle: com.mybank.account.delivery;deployed-version=1.0.1<br>
     Import-Package: com.mybank.account.admin.login;version="1.0.1";bundle-symbolic-name="com.mybank.account.admin";bundle-version="[1.0.1,1.0.1]",com.mybank.account.delivery.bycar;version="[1.0.0,2.0.0)",javax.servlet;version="2.5.0"<br>
     Deployed-Use-Bundle: com.mybank.account.admin;deployed-version=1.0.1<br>
 </DIV>
 </DIV>

 The manifest headers are as follows:

 * Manifest-Version - a version number for the manifest format.
 * Application-Version - uniquely identify the version of the application.
 Must match that in the associated APPLICATION.MF.
 * Application-SymbolicName - a name to uniquely identify the application.
 Follows the same scheme as Bundle-SymbolicName. Must match that in the
 associated APPLICATION.MF.
 * Deployed-Content: the complete list of bundles, with exact version
 numbers, that comprise the application and its dependencies.
 * Deployed-Use-Bundle - a list of bundles that satisfy the package
 dependencies of bundles in the Deployed-Content list. Each element in the
 Deployed-Use-Bundle list must provide at least one package to at least one
 bundle in the Deployed-Content list. The Deployed-Use-Bundle list is an
 exact subset of the Use-Bundle list in the APPLICATION.MF. These bundles
 will be loaded into the shared bundle space at run time. Each bundle in the
 Deployed-Use-Bundle list is guaranteed to be wired to its dependent bundles
 in the Deployed-Content list at run time.
 * Provision-Bundle - a list of additional bundles that are required as a
 result of resolving the OSGi application. Each bundle is loaded into the
 shared bundle space at run time.
 * Import-Package - a list of the packages that the bundles in the
 Deployed-Content list consume from the bundles in the Deployed-Use-Bundle
 and Provision-Bundle lists. For packages that are consumed from the
 Deployed-Use-Bundle list, the package import has ;bundle-symbolic-name and
 ;bundle-version attributes.

 Versions in APPLICATION.MF are ranges: in DEPLOYMENT.MF they are exact.
 Hence we see Application-Content: com.mybank.account.common; version=1.0.0
 having been interpreted as '1.0.0 or higher' and so resolved to 1.2.0. Also
 a common logging bundle at version 1.3.1 will be deployed with the
 application.
	Title: Applications
	<a name="Applications-AriesApplications"></a>
	# Aries Applications

	An Aries application is a collection of one or more OSGi modules that
	together provide a coherent business function. An Aries application can
	consist of modules of many different types. For example, a Aries
	application providing Web banking might consist of bundles with Web content
	(Web Application Bundles), bundles with Blueprint contexts, and bundles
	with JPA entities and persistence configuration (Persistence Bundles).

	An Aries application isolates the OSGi services offered by its contained
	modules so that they are not visible outside the application unless
	explicitly configured to be exported from the application. Aries
	applications have several ways of accepting workloads: an Aries
	applications may include Web bundles for processing HTTP workloads; it may
	export one or more of the services offered by its contained modules to
	other Aries applications or for distribution as a Web service.

	With the isolation runtime, each Aries application runs in its own isolated
	OSGi framework instance with its own OSGi service registry. Bundles in one
	Aries application cannot see bundles, services, or packages that are
	defined in another OSGi application, unless the bundles, services, or
	packages are explicitly shared by both applications. An Aries application
	can also load packages and consume OSGi services from a shared bundle
	space, that is, the OSGi framework instance that is the parent of all the
	isolated framework instances of the OSGi applications.

	<a name="Applications-StructureofanAriesapplication"></a>
	## Structure of an Aries application

	An Aries application is packaged as a zip file with a '.eba' suffix. Its
	structure is as follows:

	<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Sample Aries application structure</B></DIV><DIV class="codeContent panelContent">
	META-INF/APPLICATION.MF<br>
	bundle1.jar<br>
	bundle2.jar<br>
	bundle3.jar<br>
	</DIV>
	</DIV>

	The file must contain either an APPLICATION.MF with at least one bundle
	listed in its Application-Content header (see below), or at least one
	bundle 'by value' within the .eba. No 'by value' bundles are required if a
	valid APPLICATION.MF is present.

	Application metadata, APPLICATION.MF, stored in the .eba file defines the
	isolation scope of the bundles that the OSGi application uses. An Aries
	applicaiton can also use metadata to permit some of its constituent bundles
	to be shared. Sharing in this way can reduce the memory and resource
	requirements of a system. Shared bundles must be provided by reference
	rather than contained directly in an application.

	<a name="Applications-AriesApplicationManifest"></a>
	## Aries Application Manifest

	An Aries Application is defined using a Manifest. The Aries manifest is
	located at META-INF/APPLICATION.MF and describes modularity at the
	application level. The manifest enumerates the modules that comprise the
	Aries application along with any OSGi services exported from, or referenced
	by, those modules. The following is an example of an Aries manifest:

	<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>APPLICATION.MF</B></DIV><DIV class="codeContent panelContent">
	Manifest-Version: 1.0<br>
	Application-ManifestVersion: 1.0<br>
	Application-Name: Bank Account<br>
	Application-SymbolicName: com.mybank.account.app<br>
	Application-Version: 1.0<br>
	Application-Content: <br>
	com.mybank.account.bankWeb; version=1.0.0,<br>
	com.mybank.account.bankAccount; version=1.0.0,<br>
	com.mybank.account.common; version=1.0.0,<br>
	com.mybank.account.utility; version=1.0.0<br>
	Use-Bundle: com.mybank.account.admin;version="[1.0.0,2.0.0)"<br>
	Application-ExportService: com.mybank.account.service.AccountService<br>
	Application-ImportService:<br>
	com.mybank.security.UserAuthService;filter="(security=strong)"<br>
	</DIV>
	</DIV>

	The manifest headers are as follows:

	* Manifest-Version - a version number for the manifest format.
	* Application-ManifestVersion - identifies the application manifest version
	to which this manifest conforms
	* Application-Name - a human readable name for the application
	* Application-SymbolicName - a name to uniquely identify the application.
	Follows the same scheme as Bundle-SymbolicName.
	* Application-Version - uniquely identify the version of the application.
	The combination of symbolic name and version must be unique within an Aries
	application runtime.
	* Application-Content - a list of 'root' bundles to provision for the
	application. 'Version' identifies a version range for the bundle to be
	provisioned thus allowing flexibility. The version format is identical to
	that used for OSGi import (e.g. Import-Package).
	* Use-Bundle - a list of bundles bundles to use to satisfy the package
	dependencies of bundles in the Application-Content list. Each bundle in the
	Use-Bundle list must provide at least one package to at least one bundle in
	the Application-Content list. These bundles will be provisioned into the
	shared bundle space at run time.
	* Application-ExportService - a list of service interface names and
	optional filters identifying services provided by the application which can
	be accessed outside the application.
	* Application-ImportService - a list of service interface names and
	optional filters identifying services which the application would like to
	consume from outside the application.

	Often, you do not require a Use-Bundle header, but there are some
	situations where it is useful. You can use it to restrict the level at
	which sharing is possible. For example, you can ensure that an application
	uses the same bundle for package imports that it was tested with.
	Alternatively, you can ensure that two applications use the same bundle for
	package imports. By setting the restriction at application level, the
	bundle can remain flexible.

	<a name="Applications-AriesDeploymentManifest"></a>
	## Aries Deployment Manifest

	The Aries application model allows for the possibility that the bundles
	listed in APPLICATION.MF's Application-Content header, plus those
	optionally included within a .eba file, may have unsatisfied package or
	service dependencies. Such missing dependencies may be obtained
	('provisioned') from one or more bundle repositories. Aries will provide a
	generic 'Resolver' API which may be backed by technology such as [Felix OBR](http://felix.apache.org/site/apache-felix-osgi-bundle-repository.html)
	or [Equinox p2\|http://wiki.eclipse.org/Equinox_p2_Getting_Started]
	. Although it is possible to re-resolve an application every time it is
	installed, or even started, this may result in inconsistent behaviour as
	the contents of an associated bundle repository changes. Aries uses a
	second file, META-INF/DEPLOYMENT.MF to record a single consistent set of
	bundles that fully satisfy an application's dependencies. The bundles
	recorded in DEPLOYMENT.MF will be loaded into the runtime each time the
	application is installed. A DEPLOYMENT.MF file will be generated if one
	does not exist, or honoured if provided. Here's an example:

	<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>DEPLOYMENT.MF</B></DIV><DIV class="codeContent panelContent">
	Manifest-Version: 1.0<br>
	Application-Version: 1.0<br>
	Application-SymbolicName: com.mybank.account.app<br>
	Deployed-Content: com.mybank.account.bankWeb; deployed-version=1.0.0,<br>
	com.mybank.account.bankAccount; deployed-version=1.0.0,<br>
	com.mybank.account.common; deployed-version=1.2.0,<br>
	com.mybank.account.utility; deployed-version=1.0.0, <br>
	com.mybank.utils.logging; deployed-version=1.3.1<br>
	Provision-Bundle: com.mybank.account.delivery;deployed-version=1.0.1<br>
	Import-Package: com.mybank.account.admin.login;version="1.0.1";bundle-symbolic-name="com.mybank.account.admin";bundle-version="[1.0.1,1.0.1]",com.mybank.account.delivery.bycar;version="[1.0.0,2.0.0)",javax.servlet;version="2.5.0"<br>
	Deployed-Use-Bundle: com.mybank.account.admin;deployed-version=1.0.1<br>
	</DIV>
	</DIV>

	The manifest headers are as follows:

	* Manifest-Version - a version number for the manifest format.
	* Application-Version - uniquely identify the version of the application.
	Must match that in the associated APPLICATION.MF.
	* Application-SymbolicName - a name to uniquely identify the application.
	Follows the same scheme as Bundle-SymbolicName. Must match that in the
	associated APPLICATION.MF.
	* Deployed-Content: the complete list of bundles, with exact version
	numbers, that comprise the application and its dependencies.
	* Deployed-Use-Bundle - a list of bundles that satisfy the package
	dependencies of bundles in the Deployed-Content list. Each element in the
	Deployed-Use-Bundle list must provide at least one package to at least one
	bundle in the Deployed-Content list. The Deployed-Use-Bundle list is an
	exact subset of the Use-Bundle list in the APPLICATION.MF. These bundles
	will be loaded into the shared bundle space at run time. Each bundle in the
	Deployed-Use-Bundle list is guaranteed to be wired to its dependent bundles
	in the Deployed-Content list at run time.
	* Provision-Bundle - a list of additional bundles that are required as a
	result of resolving the OSGi application. Each bundle is loaded into the
	shared bundle space at run time.
	* Import-Package - a list of the packages that the bundles in the
	Deployed-Content list consume from the bundles in the Deployed-Use-Bundle
	and Provision-Bundle lists. For packages that are consumed from the
	Deployed-Use-Bundle list, the package import has ;bundle-symbolic-name and
	;bundle-version attributes.

	Versions in APPLICATION.MF are ranges: in DEPLOYMENT.MF they are exact.
	Hence we see Application-Content: com.mybank.account.common; version=1.0.0
	having been interpreted as '1.0.0 or higher' and so resolved to 1.2.0. Also
	a common logging bundle at version 1.3.1 will be deployed with the
	application.