Delving deeper into modularity - OSGi in Action - page 161

mandatory export attributes, which you declare using the mandatory export package
directive of the Export-Package manifest header.

MANDATORY DIRECTIVE The mandatory export package directive specifies a
comma-delimited list of attribute names that any importer must match in
order to be wired to the exported package.

To s e e h o w m a n d a t o r y a t t r i b u t e s w o r k , l e t 's m o d i f y t h e p r e v i o u s s n i p p e t t o e x p o r t i t s
package, like this:

Export-Package: javax.servlet; version="2.4.1"; private="true";
mandatory:="private"
You add the mandatory directive to the
exported package to declare the private
attribute as mandatory. Any export attribute
declared as mandatory places a constraint on
importers. If the importers don't specify a
matching value for the attribute, then they
don't match. The export attribute can't be
ignored, as shown in figure 5.6. The need for
mandatory attributes doesn't arise often;
you'll see some other use cases in the coming
sections. Until then, let's look into another
more fine-grained mechanism that bundles
can use to control what is exposed from their
exported packages.

import
javax.servlet
version="[2.4.0, 2.5.0)"
private="true"

C

B

A

export
javax.servlet
version="2.4.0"
private="true"
mandatory:="private"

import
javax.servlet
version="[2.4.0, 2.5.0)"

Figure 5.6 If an export attribute is
declared as mandatory, importing bundles
must declare the attribute and matching
value; otherwise, it won't match when the
framework resolves dependencies.

5.1.4 Export filtering

In chapter 1, we discussed the limitations of Java's rules for code visibility. There's no
way to declare module visibility, so you must use public visibility for classes accessed
across packages. This isn't necessarily problematic if you can keep your public and pri-
vate API s in separate packages, because bundles have the ability to hide packages by
not exporting them. Unfortunately, this isn't always possible, and in some cases you
end up with a public implementation class inside a package exported by the bundle.
To c o p e w i t h t h i s s i t u a t i o n , OSG i provides include and exclude export filtering direc-
tives for the Export-Package manifest header to enable fine-grained control over the
classes exposed from your bundle's exported packages.

EXCLUDE/INCLUDE DIRECTIVES The exclude and include export package
directives specify a comma-delimited list of class names to exclude or include
from the exported package, respectively.

To s e e h o w y o u c a n u s e t h e s e d i r e c t i v e s , c o n s i d e r a h y p o t h e t i c a l b u n d l e c o n t a i n i n g a
package ( org.foo.service ) with a service interface ( public class Service ), an
implementation of the service (package private class ServiceImpl ), and a utility class
( public class Util ). In this hypothetical example, the utility class is part of the private
API . It's included in this package due to dependencies on the service implementation