felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Felix > Apache Felix Dependency Manager - Reference Guide
Date Wed, 08 Sep 2010 21:25:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1810/9/1/_/styles/combined.css?spaceKey=FELIX&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/FELIX/Apache+Felix+Dependency+Manager+-+Reference+Guide">Apache
Felix Dependency Manager - Reference Guide</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~marrs">Marcel
Offermans</a>
    </h4>
        <br/>
                         <h4>Changes (23)</h4>
                                 
    
<div id="page-diffs">
            <table class="diff" cellpadding="0" cellspacing="0">
            <tr><td class="diff-unchanged" >h2. Reference Guide <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >h3. <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Services</span>
<span class="diff-added-words"style="background-color: #dfd;">Components</span>
<br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">Components
are declared by the dependency manager and can be implemented by POJOs that contain no references
to the OSGi framework whatsoever. Components are the main building blocks of your OSGi application.
They have a life cycle, can register themselves as services and have zero or more dependencies.
<br> <br></td></tr>
            <tr><td class="diff-unchanged" >h4. Life cycle <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >The dependency manager, as part
of a bundle, shares the generic bundle life cycle explained in the OSGi specification. The
life cycle of the dependency manager itself, and the <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">services</span>
<span class="diff-added-words"style="background-color: #dfd;">components</span>
it manages, can be located inside the *active* state of the hosting bundle. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >Each <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">service</span>
<span class="diff-added-words"style="background-color: #dfd;">component</span>
you define gets its own life cycle, which is explained in the state diagram below. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>TODO: add diagram <br>
<br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">...
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">If
you declare a component not by specifying an instance, but a class, the instance will be lazily
created. Also, when found, the following life cycle methods will be invoked on your component
instance: {{init}}, {{start}}, {{stop}} and {{destroy}}. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>h4. Interfaces and properties
<br> <br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Services</span>
<span class="diff-added-words"style="background-color: #dfd;">Components</span>
in the context of the dependency manager can be published as OSGi services under one or more
interface names, plus optionally a set of properties. This is no different than a normal OSGi
service. It&#39;s important to mention that you don&#39;t have to register a service.
If you don&#39;t, you basically created a component that can do work and have dependencies
and a managed life cycle. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>h4. Composition <br>
<br></td></tr>
            <tr><td class="diff-changed-lines" >When implementing more complex
<span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">services,</span>
<span class="diff-added-words"style="background-color: #dfd;">components,</span>
you often find yourself using more than one instance. However, several of these instances
might want to have dependencies injected. In such cases you need to tell the dependency manager
which instances to consider. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>h4. Factories <br>
<br></td></tr>
            <tr><td class="diff-changed-lines" >Out of the box, there already
is support for lazy instantiation, meaning that the dependency manager can create <span
class="diff-added-words"style="background-color: #dfd;">component</span> instances
for you when their required dependencies are resolved. However, sometimes creating a single
instance using a default constructor is not enough. In those cases, you can tell the dependency
manager to delegate the creation process to a factory. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>h4. Aspects <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h4. Resource Adapters <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >Resource adapters work just like
adapters, but instead of working with services, they work with resources. <span class="diff-changed-words">Resources<span
class="diff-added-chars"style="background-color: #dfd;">, represented as a URL,</span></span>
are an abstraction introduced to provide a generic way of dealing with &quot;blobs&quot;
and can be resources inside a bundle, filesystem or some kind of data store. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>h3. Dependencies <br>
<br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">...
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">The
dependency manager supports many different types of dependencies, all of which can be required
or optional. A dependency can be added to one or more components and it is possible to add
them dynamically (even from within the component itself if necessary, which allows for some
really dynamic dependency configuration). <br></td></tr>
            <tr><td class="diff-unchanged" > <br>h4. Injection <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">
<br>One way to deal with dependencies is to have them injected into your component instances
automatically. All you need to do is simply declare a field of the same type as your dependency,
make the member volatile so any changes will become visible immediately and you&#39;re
done. If a dependency is optional, a null object will be injected if the dependency is not
available. <br> <br>Sometimes you need more control over injection, so optionally
you can even specify the name of the field to inject into. This allows you to depend on different
dependencies of the same type, or simply to prevent injection into more than one field. <br>
<br></td></tr>
            <tr><td class="diff-unchanged" >h4. Callbacks <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">
<br>When keeping track of multiple instances of a dependency, or when you simply want
something to happen whenever a dependency becomes (un)available or changes, you can define
callbacks, like {{added}}, {{changed}} and {{removed}}. Optionally, you can provide the dependency
manager with an instance to invoke these callback methods on. If you don&#39;t, they&#39;ll
be invoked on the component instance. <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h4. Types of Dependencies <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">
<br>Out of the box, several types of dependencies are supported: service, bundle, configuration,
resource and temporal service. However, it&#39;s quite easy to add your own custom type
of dependency too. <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h5. Service <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">
<br>A service dependency allows you to depend on a service, either by type or by using
an additional filter condition. You can even depend on an existing service directly by providing
a reference to it. <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h5. Bundle <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">
<br>A bundle dependency allows you to depend on a bundle in a certain set of states,
as indicated by a state mask. You can also use a filter condition that is matched against
all manifest entries. Finally you can provide a reference to an existing bundle. <br>
<br></td></tr>
            <tr><td class="diff-unchanged" >h5. Configuration <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">
<br>A configuration dependency is always required, and allows you to depend on the availability
of a valid configuration for your component. <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h5. Resource <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">
<br>A resource dependency allows you to depend on a resource. A resource is a URL and
you can use a filter condition based on protocol, host, port, path and URL. <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h5. Temporal Service <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">
<br>A temporal service dependency is a special type of service dependency which does
not go away anymore. If you invoke it, and in reality the service is temporarily not available,
your call will block until a configurable time-out passes. If during that time the service
becomes available again, the new service method is invoked. If not, you will get an exception
indicating the time-out expired. <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h5. Implementing Your Own Dependency
<br> <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">All
dependencies share a common API which you can implement yourself if you need a special type
of dependency. <br> <br>TODO explain this, there is an example test that contains
a simple demo <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h3. Monitoring and Shell <br>
<br>h4. Service Interfaces for Monitoring <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">
<br></td></tr>
            <tr><td class="diff-changed-lines" >h4. Apache <span class="diff-changed-words">Felix<span
class="diff-added-chars"style="background-color: #dfd;">, Gogo</span></span>
and Eclipse Equinox Shell <br></td></tr>
        </table>
</div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h2><a name="ApacheFelixDependencyManager-ReferenceGuide-ReferenceGuide"></a>Reference
Guide</h2>

<h3><a name="ApacheFelixDependencyManager-ReferenceGuide-Components"></a>Components</h3>

<p>Components are declared by the dependency manager and can be implemented by POJOs
that contain no references to the OSGi framework whatsoever. Components are the main building
blocks of your OSGi application. They have a life cycle, can register themselves as services
and have zero or more dependencies.</p>

<h4><a name="ApacheFelixDependencyManager-ReferenceGuide-Lifecycle"></a>Life
cycle</h4>

<p>The dependency manager, as part of a bundle, shares the generic bundle life cycle
explained in the OSGi specification. The life cycle of the dependency manager itself, and
the components it manages, can be located inside the <b>active</b> state of the
hosting bundle.</p>

<p>Each component you define gets its own life cycle, which is explained in the state
diagram below.</p>

<p>TODO: add diagram</p>

<p>If you declare a component not by specifying an instance, but a class, the instance
will be lazily created. Also, when found, the following life cycle methods will be invoked
on your component instance: <tt>init</tt>, <tt>start</tt>, <tt>stop</tt>
and <tt>destroy</tt>.</p>

<h4><a name="ApacheFelixDependencyManager-ReferenceGuide-Interfacesandproperties"></a>Interfaces
and properties</h4>

<p>Components in the context of the dependency manager can be published as OSGi services
under one or more interface names, plus optionally a set of properties. This is no different
than a normal OSGi service. It's important to mention that you don't have to register a service.
If you don't, you basically created a component that can do work and have dependencies and
a managed life cycle.</p>

<h4><a name="ApacheFelixDependencyManager-ReferenceGuide-Composition"></a>Composition</h4>

<p>When implementing more complex components, you often find yourself using more than
one instance. However, several of these instances might want to have dependencies injected.
In such cases you need to tell the dependency manager which instances to consider.</p>

<h4><a name="ApacheFelixDependencyManager-ReferenceGuide-Factories"></a>Factories</h4>

<p>Out of the box, there already is support for lazy instantiation, meaning that the
dependency manager can create component instances for you when their required dependencies
are resolved. However, sometimes creating a single instance using a default constructor is
not enough. In those cases, you can tell the dependency manager to delegate the creation process
to a factory.</p>

<h4><a name="ApacheFelixDependencyManager-ReferenceGuide-Aspects"></a>Aspects</h4>

<p>Aspects, as part of aspect oriented programming, can be used in a dynamic environment
such as OSGi to "extend" existing services and add certain "capabilities" to them. Examples
of these are adding a specific caching mechanism to a storage service or implementing logging.
Aspects in OSGi can be applied to services and can be added and removed at runtime.</p>

<h4><a name="ApacheFelixDependencyManager-ReferenceGuide-Adapters"></a>Adapters</h4>

<p>Adapters, like aspects, are used to "extend" existing services, and can publish different
services based on the existing one. An example would be implementing a management interface.</p>

<h4><a name="ApacheFelixDependencyManager-ReferenceGuide-ResourceAdapters"></a>Resource
Adapters</h4>

<p>Resource adapters work just like adapters, but instead of working with services,
they work with resources. Resources, represented as a URL, are an abstraction introduced to
provide a generic way of dealing with "blobs" and can be resources inside a bundle, filesystem
or some kind of data store.</p>

<h3><a name="ApacheFelixDependencyManager-ReferenceGuide-Dependencies"></a>Dependencies</h3>

<p>The dependency manager supports many different types of dependencies, all of which
can be required or optional. A dependency can be added to one or more components and it is
possible to add them dynamically (even from within the component itself if necessary, which
allows for some really dynamic dependency configuration).</p>

<h4><a name="ApacheFelixDependencyManager-ReferenceGuide-Injection"></a>Injection</h4>

<p>One way to deal with dependencies is to have them injected into your component instances
automatically. All you need to do is simply declare a field of the same type as your dependency,
make the member volatile so any changes will become visible immediately and you're done. If
a dependency is optional, a null object will be injected if the dependency is not available.</p>

<p>Sometimes you need more control over injection, so optionally you can even specify
the name of the field to inject into. This allows you to depend on different dependencies
of the same type, or simply to prevent injection into more than one field.</p>

<h4><a name="ApacheFelixDependencyManager-ReferenceGuide-Callbacks"></a>Callbacks</h4>

<p>When keeping track of multiple instances of a dependency, or when you simply want
something to happen whenever a dependency becomes (un)available or changes, you can define
callbacks, like <tt>added</tt>, <tt>changed</tt> and <tt>removed</tt>.
Optionally, you can provide the dependency manager with an instance to invoke these callback
methods on. If you don't, they'll be invoked on the component instance.</p>

<h4><a name="ApacheFelixDependencyManager-ReferenceGuide-TypesofDependencies"></a>Types
of Dependencies</h4>

<p>Out of the box, several types of dependencies are supported: service, bundle, configuration,
resource and temporal service. However, it's quite easy to add your own custom type of dependency
too.</p>

<h5><a name="ApacheFelixDependencyManager-ReferenceGuide-Service"></a>Service</h5>

<p>A service dependency allows you to depend on a service, either by type or by using
an additional filter condition. You can even depend on an existing service directly by providing
a reference to it.</p>

<h5><a name="ApacheFelixDependencyManager-ReferenceGuide-Bundle"></a>Bundle</h5>

<p>A bundle dependency allows you to depend on a bundle in a certain set of states,
as indicated by a state mask. You can also use a filter condition that is matched against
all manifest entries. Finally you can provide a reference to an existing bundle.</p>

<h5><a name="ApacheFelixDependencyManager-ReferenceGuide-Configuration"></a>Configuration</h5>

<p>A configuration dependency is always required, and allows you to depend on the availability
of a valid configuration for your component.</p>

<h5><a name="ApacheFelixDependencyManager-ReferenceGuide-Resource"></a>Resource</h5>

<p>A resource dependency allows you to depend on a resource. A resource is a URL and
you can use a filter condition based on protocol, host, port, path and URL.</p>

<h5><a name="ApacheFelixDependencyManager-ReferenceGuide-TemporalService"></a>Temporal
Service</h5>

<p>A temporal service dependency is a special type of service dependency which does
not go away anymore. If you invoke it, and in reality the service is temporarily not available,
your call will block until a configurable time-out passes. If during that time the service
becomes available again, the new service method is invoked. If not, you will get an exception
indicating the time-out expired.</p>

<h5><a name="ApacheFelixDependencyManager-ReferenceGuide-ImplementingYourOwnDependency"></a>Implementing
Your Own Dependency</h5>

<p>All dependencies share a common API which you can implement yourself if you need
a special type of dependency.</p>

<p>TODO explain this, there is an example test that contains a simple demo</p>

<h3><a name="ApacheFelixDependencyManager-ReferenceGuide-MonitoringandShell"></a>Monitoring
and Shell</h3>

<h4><a name="ApacheFelixDependencyManager-ReferenceGuide-ServiceInterfacesforMonitoring"></a>Service
Interfaces for Monitoring</h4>

<h4><a name="ApacheFelixDependencyManager-ReferenceGuide-ApacheFelix%2CGogoandEclipseEquinoxShell"></a>Apache
Felix, Gogo and Eclipse Equinox Shell</h4>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/FELIX/Apache+Felix+Dependency+Manager+-+Reference+Guide">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=9374249&revisedVersion=3&originalVersion=2">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/FELIX/Apache+Felix+Dependency+Manager+-+Reference+Guide?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message