The OSGi API is rich and introspective supporting the local management of bundles, services and other items. Since the API has a lot of behavior and is not designed for serialization, any management model must design its own representation of the relevant OSGi objects for communication with remote management systems. We see this in the Management Model Specification for JMX™ Technology, the Dmt Admin Service Specification and Residential Device Management Tree Specification: the Management Model Specification for JMX™ Technology must define the MBeans and the Residential Device Management Tree Specification must define the tree representation.
The OSGi API continues to evolve and at each update of the OSGi API, the management models will all need to update their representations of the OSGi objects. Having standard, simple, easy to serialize and deserialize objects which represent the relevant OSGi objects will make it easier for the management model to keep up with changes in the OSGi API. Therefore, this specification defines Data Transfer Objects for OSGi in general and well as specific Data Transfer Objects for the Core specification. Other OSGi specifications may be updated over time to define Data Transfer Objects specific to their domain.
-
Easy Serialization/Deserialization - Must be easily serializable. That is, no special serialization/deserialization logic must be required. Serialization must be possible simply by introspection and object graphs must be a tree.
-
No Behavior - Must have no behavior. That is, no methods other than the default public constructor.
-
Public - Must have only public fields. That is, no private implementation detail.
-
Limited Field Types - Must only use a limited selection of field types.
-
Extendable - May extend other Data Transfer Object types.
-
Snapshot - Does not track changes to represented runtime object.
-
Not Thread Safe - External synchronization is needed.
-
Instantiation - A means is provided to create Data Transfer Objects for the runtime objects they represent.
-
Data Transfer Object (DTO) - An object for carrying data between processes. A Data Transfer Object does not have any behavior. See [1] Data Transfer Object.
-
Runtime Object - A runtime object being represented by a Data Transfer Object. The runtime object can have complex behavior.
A Data Transfer Object is used to represent the state of a related runtime object in a form suitable for easy transfer to some receiver. The receiver can be in the same Java VM but is more likely in another process or on another system that is remote. All Data Transfer Objects are easily serializable having only public fields of a limited set of type. These types are:
-
Primitive types
-
Wrapper classes for the primitive types
-
String -
enum
-
Data Transfer Objects
-
List -
Set -
Map -
array
The List, Set, Map and array aggregates must only hold objects of
the listed types. The types for Map keys are limited to primitive wrapper
classes, String, enums, and Version.
Data Transfer Objects are public classes with no methods, other than the compiler supplied default constructor, having only public fields limited to the easily serializable types mentioned above. The org.osgi.dto package defines the basic rules and the abstract base DTO class which Data Transfer Objects must extend.
A Data Transfer Object is a representation of a runtime object at the point in time the Data Transfer Object was created. Data Transfer Objects do not track state changes in the represented runtime object. Since Data Transfer Objects are simply fields with no method behavior, modifications to Data Transfer Object are inherently not thread safe. Care must be taken to safely publish Data Transfer Objects for use by other threads as well as proper synchronization if a Data Transfer Object is mutated by one of the threads.
The object graph from a Data Transfer Object must be a tree to simplify serialization and deserialization.
Data Transfer Objects should follow a naming convention for the
package containing the Data Transfer Object as well as the Data Transfer
Object type. For the package name, we start with the package name
containing the runtime type for which the Data Transfer Object is a
representation. A dto segment is suffixed to the package
name. For example, a Data Transfer Object representing a runtime type in
the org.osgi.service.foo package will be in the Data
Transfer Object package name is
org.osgi.service.foo.dto.
The name of the Data Transfer Object type should be the name of
the runtime type for which the Data Transfer Object is a representation
followed by DTO. So for a type Widget, the
Data Transfer Object for that type should be WidgetDTO.
Sometimes the entity for which the Data Transfer Object provides a
representation does not exists as a runtime type. In this case, the name
of entity with a DTO suffix should be used. For example,
EntityDTO.
Putting both the package and type Data Transfer Object naming
conventions together, the fully qualified name for the Data Transfer
Object representing the runtime type
org.osgi.service.foo.Widget would be
org.osgi.service.foo.dto.WidgetDTO.
Data Transfer Objects are defined for several important Core
specification objects including Bundle, the Framework, and
ServiceReference as well as the Resource API types, Start
Level API types and Bundle Wiring API types.
A BundleDTO represents information about a single bundle such as the id of the bundle, the current state of the bundle and the symbolic name and version of the bundle.
A ServiceReferenceDTO represents information about a single registered service such as the service properties, the bundle which registered the service and the bundles using the service.
A FrameworkDTO represents information about the Framework such as the list of installed bundles, the registered services and the launch properties of the framework.
CapabilityDTO, RequirementDTO, ResourceDTO, WiringDTO and WireDTO represent the capabilities and requirements wiring information of the Resource API. The following figure shows the effective relationship between these Data Transfer Object types. Since the graph of Data Transfer Objects must be a tree, some references are indirect.
BundleRevisionDTO, BundleWiringDTO, and BundleWireDTO represent the capabilities and requirements wiring information of the Bundle Wiring API. The following figure shows the effective relationship between these Data Transfer Object types. Since the graph of Data Transfer Objects must be a tree, some references are indirect.
FrameworkWiringDTO represents the complete capabilities and requirements wiring information for all the bundles in the framework.
A BundleStartLevelDTO represents information about the start level information of a bundle such as the assigned start level, the activation policy used and the whether the bundle is persistently started.
A FrameworkStartLevelDTO provides the start level information about the Framework such as the active start level and the initial bundle start level assigned to newly installed bundles.
The adapt(Class) method allows the Bundle to be adapted to
different types. The adapt method is used to obtain the Core
Data Transfer Objects. For example, the adapt method can be
used to adapt a Bundle object to the current BundleDTO
object. The adapt method can be used as follows:
// DTO for the bundle
BundleDTO bundleDTO = bundle.adapt(BundleDTO.class);
// DTO for the current bundle wiring
BundleWiringDTO bundleWiringDTO = bundle.adapt(BundleWiringDTO.class);
// DTO for the current bundle revision
BundleRevisionDTO bundleRevisionDTO = bundle.adapt(BundleRevisionDTO.class);The following table shows the Core Data Transfer Objects that can be
obtained from a Bundle via the adapt method.
Table 57.1 Data Transfer Objects that can be adapted from Bundle
| Class | Description |
|---|---|
|
The Bundle Data Transfer Object for the bundle. |
|
|
An array of Service Reference Data Transfer Objects
for the registered services of the bundle. If the bundle has no
registered services, the result is an empty array. If the bundle
does not have a valid bundle context, the result is
|
|
|
The Bundle Revision Data Transfer Object for the
bundle. If the bundle is uninstalled or otherwise does not have a
bundle revision, the result is |
|
|
The Bundle Revision Data Transfer Objects for the
bundle. The first revision is the current revision. If the bundle
is uninstalled, the result is |
|
|
The Bundle Wiring Data Transfer Object for the
bundle. If the bundle is unresolved or otherwise does not have a
bundle wiring, the result is |
|
|
The Bundle Wiring Data Transfer Objects for the
bundle. The first wiring is the current wiring. If the bundle is
uninstalled, the result is |
|
|
The Bundle Start Level Data Transfer Object for the
bundle. If the bundle is uninstalled, the result is
|
|
|
The Framework Start Level Data Transfer Object if the
bundle is the System Bundle. If the bundle is not the System
Bundle, the result is |
|
|
The Framework Data Transfer Object if the bundle is
the System Bundle. If the bundle is not the System Bundle, the
result is |
|
|
The Framework Wiring Data Transfer Object if the
bundle is the System Bundle. If the bundle is not the System
Bundle, the result is |
The adapt(Class) method allows the Service Reference to be adapted
to different types. The adapt method is used to obtain the
Core Data Transfer Objects. For example, the adapt method can
be used to adapt a Service Reference object to the current
ServiceReferenceDTO object. The adapt method can be used as
follows:
// DTO for the service reference
ServiceReferenceDTO referenceDTO = reference.adapt(ServiceReferenceDTO.class);The following table shows the Core Data Transfer Objects that can be
obtained from a Service Reference via the adapt
method.
Table 57.2 Data Transfer Objects that can be adapted from ServiceReference
| Class | Description |
|---|---|
|
A Service Reference Data Transfer Object for the Service Reference. |
Data Transfer Objects have no behavior by definition and thus no
permissions are applicable to their use. To obtain Data Transfer Objects
from a Bundle or ServiceReference object via the adapt
method, AdaptPermission[<dtotype>,ADAPT] is required
for the desired Data Transfer Object type.
OSGi Data Transfer Object Package Version 1.1.
Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. This package has two types of users: the consumers that use the API in this package and the providers that implement the API in this package.
Example import for consumers using the API in this package:
Import-Package: org.osgi.dto; version="[1.1,2.0)"
Example import for providers implementing the API in this package:
Import-Package: org.osgi.dto; version="[1.1,1.2)"
-
DTO- Super type for Data Transfer Objects.
Super type for Data Transfer Objects.
A Data Transfer Object (DTO) is easily serializable having only public fields of primitive types and their wrapper classes, String, enums, Version, and DTOs. List, Set, Map, and array aggregates may also be used. The aggregates must only hold objects of the listed types or aggregates. The types for Map keys are limited to primitive wrapper classes, String, enums, and Version.
The object graph from a Data Transfer Object must be a tree to simplify serialization and deserialization.
Not Thread-safe
OSGi Data Transfer Object Framework Package Version 1.8.
Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. This package has two types of users: the consumers that use the API in this package and the providers that implement the API in this package.
Example import for consumers using the API in this package:
Import-Package: org.osgi.framework.dto; version="[1.8,2.0)"
Example import for providers implementing the API in this package:
Import-Package: org.osgi.framework.dto; version="[1.8,1.9)"
-
BundleDTO- Data Transfer Object for a Bundle. -
FrameworkDTO- Data Transfer Object for a Framework. -
ServiceReferenceDTO- Data Transfer Object for a ServiceReference.
Data Transfer Object for a Bundle.
A Bundle can be adapted to provide a BundleDTO for the Bundle.
Not Thread-safe
The time when the bundle was last modified.
Data Transfer Object for a Framework.
The System Bundle can be adapted to provide a FrameworkDTO for the
framework of the system bundle. A FrameworkDTO obtained from a
framework will contain only the launch properties of the framework. These
properties will not include the System properties.
Not Thread-safe
The bundles that are installed in the framework.
The launch properties of the framework. The value type must be a numerical type, Boolean, String, DTO or an array of any of the former.
The services that are registered in the framework.
Data Transfer Object for a ServiceReference.
ServiceReferenceDTOs for all registered services can be obtained from
a FrameworkDTO. A ServiceReference can be adapted to a
ServiceReferenceDTO. A started Bundle can be adapted to provide a
ServiceReferenceDTO[] of the services registered by the Bundle. A
ServiceReferenceDTO obtained from a framework must convert service
property values which are not valid value types for DTOs to type
String using String.valueOf(Object).
Not Thread-safe
The id of the bundle that registered the service.
The properties for the service. The value type must be a numerical type, Boolean, String, DTO or an array of any of the former.
The ids of the bundles that are using the service.
OSGi Data Transfer Object Framework Start Level Package Version 1.0.
Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. This package has two types of users: the consumers that use the API in this package and the providers that implement the API in this package.
Example import for consumers using the API in this package:
Import-Package: org.osgi.framework.startlevel.dto; version="[1.0,2.0)"
Example import for providers implementing the API in this package:
Import-Package: org.osgi.framework.startlevel.dto; version="[1.0,1.1)"
-
BundleStartLevelDTO- Data Transfer Object for a BundleStartLevel. -
FrameworkStartLevelDTO- Data Transfer Object for a FrameworkStartLevel.
Data Transfer Object for a BundleStartLevel.
An installed Bundle can be adapted to provide a BundleStartLevelDTO
for the Bundle.
Not Thread-safe
The bundle's autostart setting indicates that the activation policy declared in the bundle manifest must be used.
The id of the bundle associated with this start level.
The bundle's autostart setting indicates it must be started.
The assigned start level value for the bundle.
Data Transfer Object for a FrameworkStartLevel.
The System Bundle can be adapted to provide a FrameworkStartLevelDTO
for the framework of the Bundle.
Not Thread-safe
The initial start level value that is assigned to a bundle when it is first installed.
The active start level value for the framework.
OSGi Data Transfer Object Framework Wiring Package Version 1.3.
Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. This package has two types of users: the consumers that use the API in this package and the providers that implement the API in this package.
Example import for consumers using the API in this package:
Import-Package: org.osgi.framework.wiring.dto; version="[1.3,2.0)"
Example import for providers implementing the API in this package:
Import-Package: org.osgi.framework.wiring.dto; version="[1.3,1.4)"
-
BundleRevisionDTO- Data Transfer Object for a BundleRevision. -
BundleWireDTO- Data Transfer Object for a BundleWire. -
BundleWiringDTO- Data Transfer Object for a BundleWiring graph. -
BundleWiringDTO.NodeDTO- Data Transfer Object for a BundleWiring node. -
FrameworkWiringDTO- Data Transfer Object for the wiring graph of the framework.
Data Transfer Object for a BundleRevision.
An installed Bundle can be adapted to provide a BundleRevisionDTO for
the current revision of the Bundle. BundleRevisionDTO objects for all
in use revisions of the Bundle can be obtained by adapting the bundle to
BundleRevisionDTO[].
Not Thread-safe
The id of the bundle associated with the bundle revision.
The symbolic name of the bundle revision.
Data Transfer Object for a BundleWire.
BundleWireDTOs are referenced BundleWiringDTO.NodeDTOs.
Not Thread-safe
The identifier of the provider wiring for the bundle wire.
The identifier of the requiring wiring for the bundle wire.
Data Transfer Object for a BundleWiring graph.
An installed Bundle can be adapted to provide a BundleWiringDTO for
the current wiring Bundle. BundleWiringDTO objects for all in use
wirings of the Bundle can be obtained by adapting the bundle to
BundleWiringDTO[].
Not Thread-safe
The id of the bundle associated with the bundle wiring graph.
The set of wiring nodes referenced by the wiring graph.
All wiring nodes referenced by wiring node identifiers in the wiring graph are contained in this set.
The set of resources referenced by the wiring graph.
All resources referenced by resource identifiers in the wiring graph are contained in this set.
The identifier of the root wiring node of the bundle wiring graph.
Data Transfer Object for a BundleWiring node.
The providedWires field must contain an array of BundleWireDTOs. The requiredWires field must contain an array of BundleWireDTOs.
Not Thread-safe
The current state of the bundle wiring. The bundle wiring's current setting indicates that the bundle wiring is the current bundle wiring for the bundle.
The bundle wiring's in use setting indicates that the bundle wiring is in use.
Data Transfer Object for the wiring graph of the framework.
The system bundle can be adapted to provide the FrameworkWiringDTO.
Only the system bundle can be adapted to a FrameworkWiringDTO object
1.3
Not Thread-safe
The set of resources referenced by the wiring graph of the framework.
All resources referenced by resource identifiers in the wiring graph are contained in this set.
The set of wiring nodes referenced by the wiring graph of the framework.
All wiring nodes referenced by wiring node identifiers in the wiring graph are contained in this set.
OSGi Data Transfer Object Resource Package Version 1.0.
Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. This package has two types of users: the consumers that use the API in this package and the providers that implement the API in this package.
Example import for consumers using the API in this package:
Import-Package: org.osgi.resource.dto; version="[1.0,2.0)"
Example import for providers implementing the API in this package:
Import-Package: org.osgi.resource.dto; version="[1.0,1.1)"
-
CapabilityDTO- Data Transfer Object for a Capability. -
CapabilityRefDTO- Data Transfer Object for a reference to a Capability. -
RequirementDTO- Data Transfer Object for a Requirement. -
RequirementRefDTO- Data Transfer Object for a reference to a Requirement. -
ResourceDTO- Data Transfer Object for a Resource. -
WireDTO- Data Transfer Object for a Wire. -
WiringDTO- Data Transfer Object for a Wiring node.
Data Transfer Object for a Capability.
Not Thread-safe
The attributes for the capability.
The value type must be a numerical type, Boolean, String, DTO or an array of any of the former.
The directives for the capability.
The unique identifier of the capability.
This identifier is transiently assigned and may vary across restarts.
The identifier of the resource declaring the capability.
Data Transfer Object for a reference to a Capability.
Not Thread-safe
The identifier of the resource declaring the capability.
Data Transfer Object for a Requirement.
Not Thread-safe
The attributes for the requirement.
The value type must be a numerical type, Boolean, String, DTO or an array of any of the former.
The directives for the requirement.
The unique identifier of the requirement.
This identifier is transiently assigned and may vary across restarts.
The identifier of the resource declaring the requirement.
Data Transfer Object for a reference to a Requirement.
Not Thread-safe
The identifier of the requirement in the resource.
The identifier of the resource declaring the requirement.
Data Transfer Object for a Resource.
Not Thread-safe
The capabilities of the resource.
The unique identifier of the resource.
This identifier is transiently assigned and may vary across restarts.
The requirements of the resource.
Data Transfer Object for a Wire.
Not Thread-safe
Reference to the Capability for the wire.
The identifier of the provider resource for the wire.
Reference to the Requirement for the wire.
The identifier of the requiring resource for the wire.
Data Transfer Object for a Wiring node.
Not Thread-safe
The references to the capabilities for the wiring node.
The unique identifier of the wiring node.
This identifier is transiently assigned and may vary across restarts.
The provided wires for the wiring node.
The required wires for the wiring node.
The references to the requirements for the wiring node.
The identifier of the resource associated with the wiring node.
[1]Data Transfer Objecthttps://en.wikipedia.org/wiki/Data_transfer_object
-
Updated Obtaining Core Data Transfer Objects to reflect that ServiceReference can now be adapted to ServiceReferenceDTO.
-
Clarified that the allowed key types for Map values in DTOs are limited to primitive wrapper classes,
String, enums, andVersion.