57 Data Transfer Objects Specification

57.1 Introduction

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.

57.1.1 Essentials

  • 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.

57.1.2 Entities

  • 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.

57.2 Data Transfer Object

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

  • Version

  • Data Transfer Objects

  • List

  • Set

  • Map

  • array

The List, Set, Map and array aggregates must only hold objects of the listed types.

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.

57.2.1 Naming Conventions

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.

57.3 Core Data Transfer Objects

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.

57.3.1 Framework Data Transfer Objects

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.

57.3.2 Resource API Data Transfer Objects

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.

Figure 57.1 Resource API Data Transfer Objects

Resource API Data Transfer Objects

57.3.3 Bundle Wiring API Data Transfer Objects

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.

Figure 57.2 Bundle Wiring API Data Transfer Objects

Bundle Wiring API Data Transfer Objects

FrameworkWiringDTO represents the complete capabilities and requirements wiring information for all the bundles in the framework.

57.3.4 Start Level API Data Transfer Objects

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.

57.4 Obtaining Core Data Transfer Objects

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 via the adapt method.

Table 57.1 Data Transfer Objects that can be adapted from Bundle

Class Description

BundleDTO

The Bundle Data Transfer Object for the bundle.

ServiceReferenceDTO[]

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 null.

BundleRevisionDTO

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 null.

BundleRevisionDTO[]

The Bundle Revision Data Transfer Objects for the bundle. The first revision is the current revision. If the bundle is uninstalled, the result is null.

BundleWiringDTO

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 null.

BundleWiringDTO[]

The Bundle Wiring Data Transfer Objects for the bundle. The first wiring is the current wiring. If the bundle is uninstalled, the result is null.

BundleStartLevelDTO

The Bundle Start Level Data Transfer Object for the bundle. If the bundle is uninstalled, the result is null.

FrameworkStartLevelDTO

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 null.

FrameworkDTO

The Framework Data Transfer Object if the bundle is the System Bundle. If the bundle is not the System Bundle, the result is null.

FrameworkWiringDTO

The Framework Wiring Data Transfer Object if the bundle is the System Bundle. If the bundle is not the System Bundle, the result is null.


57.5 Security

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 object via the adapt method, AdaptPermission[<dtotype>,ADAPT] is required for the desired Data Transfer Object type.

57.6 org.osgi.dto

Version 1.1

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)"

57.6.1 Summary

  • DTO - Super type for Data Transfer Objects.

57.6.2 public abstract class DTO

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, Strings, 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 object graph from a Data Transfer Object must be a tree to simplify serialization and deserialization.

Not Thread-safe

57.6.2.1 public DTO()

57.6.2.2 public String toString()

Return a string representation of this DTO suitable for use when debugging.

The format of the string representation is not specified and subject to change.

A string representation of this DTO suitable for use when debugging.

57.7 org.osgi.framework.dto

Version 1.8

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)"

57.7.1 Summary

57.7.2 public class BundleDTO
extends DTO

Data Transfer Object for a Bundle.

A Bundle can be adapted to provide a BundleDTO for the Bundle.

Not Thread-safe

57.7.2.1 public long id

The bundle's unique identifier.

Bundle.getBundleId()

57.7.2.2 public long lastModified

The time when the bundle was last modified.

Bundle.getLastModified()

57.7.2.3 public int state

The bundle's state.

Bundle.getState()

57.7.2.4 public String symbolicName

The bundle's symbolic name.

Bundle.getSymbolicName()

57.7.2.5 public String version

The bundle's version.

Bundle.getVersion()

57.7.2.6 public BundleDTO()

57.7.3 public class FrameworkDTO
extends DTO

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

57.7.3.1 public List<BundleDTO> bundles

The bundles that are installed in the framework.

BundleContext.getBundles()

57.7.3.2 public Map<String, Object> properties

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.

BundleContext.getProperty(String)

57.7.3.3 public List<ServiceReferenceDTO> services

The services that are registered in the framework.

BundleContext.getServiceReferences(String, String)

57.7.3.4 public FrameworkDTO()

57.7.4 public class ServiceReferenceDTO
extends DTO

Data Transfer Object for a ServiceReference.

ServiceReferenceDTOs for all registered services can be obtained from a FrameworkDTO. 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

57.7.4.1 public long bundle

The id of the bundle that registered the service.

ServiceReference.getBundle()

57.7.4.2 public long id

The id of the service.

Constants.SERVICE_ID

57.7.4.3 public Map<String, Object> properties

The properties for the service. The value type must be a numerical type, Boolean, String, DTO or an array of any of the former.

ServiceReference.getProperty(String)

57.7.4.4 public long[] usingBundles

The ids of the bundles that are using the service.

ServiceReference.getUsingBundles()

57.7.4.5 public ServiceReferenceDTO()

57.8 org.osgi.framework.startlevel.dto

Version 1.0

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)"

57.8.1 Summary

57.8.2 public class BundleStartLevelDTO
extends DTO

Data Transfer Object for a BundleStartLevel.

An installed Bundle can be adapted to provide a BundleStartLevelDTO for the Bundle.

Not Thread-safe

57.8.2.1 public boolean activationPolicyUsed

The bundle's autostart setting indicates that the activation policy declared in the bundle manifest must be used.

BundleStartLevel.isActivationPolicyUsed()

57.8.2.2 public long bundle

The id of the bundle associated with this start level.

BundleStartLevel.getBundle()

57.8.2.3 public boolean persistentlyStarted

The bundle's autostart setting indicates it must be started.

BundleStartLevel.isPersistentlyStarted()

57.8.2.4 public int startLevel

The assigned start level value for the bundle.

BundleStartLevel.getStartLevel()

57.8.2.5 public BundleStartLevelDTO()

57.8.3 public class FrameworkStartLevelDTO
extends DTO

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

57.8.3.1 public int initialBundleStartLevel

The initial start level value that is assigned to a bundle when it is first installed.

FrameworkStartLevel.getInitialBundleStartLevel()

57.8.3.2 public int startLevel

The active start level value for the framework.

FrameworkStartLevel.getStartLevel()

57.8.3.3 public FrameworkStartLevelDTO()

57.9 org.osgi.framework.wiring.dto

Version 1.3

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)"

57.9.1 Summary

57.9.2 public class BundleRevisionDTO
extends ResourceDTO

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

57.9.2.1 public long bundle

The id of the bundle associated with the bundle revision.

BundleRevision.getBundle()

57.9.2.2 public String symbolicName

The symbolic name of the bundle revision.

BundleRevision.getSymbolicName()

57.9.2.3 public int type

The type of the bundle revision.

BundleRevision.getTypes()

57.9.2.4 public String version

The version of the bundle revision.

BundleRevision.getVersion()

57.9.2.5 public BundleRevisionDTO()

57.9.3 public class BundleWireDTO
extends WireDTO

Data Transfer Object for a BundleWire.

BundleWireDTOs are referenced BundleWiringDTO.NodeDTOs.

Not Thread-safe

57.9.3.1 public int providerWiring

The identifier of the provider wiring for the bundle wire.

WiringDTO.id, BundleWire.getProviderWiring()

57.9.3.2 public int requirerWiring

The identifier of the requiring wiring for the bundle wire.

WiringDTO.id, BundleWire.getRequirerWiring()

57.9.3.3 public BundleWireDTO()

57.9.4 public class BundleWiringDTO
extends DTO

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

57.9.4.1 public long bundle

The id of the bundle associated with the bundle wiring graph.

BundleWiring.getBundle()

57.9.4.2 public Set<BundleWiringDTO.NodeDTO> nodes

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.

57.9.4.3 public Set<BundleRevisionDTO> resources

The set of resources referenced by the wiring graph.

All resources referenced by resource identifiers in the wiring graph are contained in this set.

57.9.4.4 public int root

The identifier of the root wiring node of the bundle wiring graph.

WiringDTO.id

57.9.4.5 public BundleWiringDTO()

57.9.5 public static class BundleWiringDTO.NodeDTO
extends WiringDTO

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

57.9.5.1 public boolean current

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.

BundleWiring.isCurrent()

57.9.5.2 public boolean inUse

The bundle wiring's in use setting indicates that the bundle wiring is in use.

BundleWiring.isInUse()

57.9.5.3 public NodeDTO()

57.9.6 public class FrameworkWiringDTO
extends DTO

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

57.9.6.1 public Set<BundleRevisionDTO> resources

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.

57.9.6.2 public Set<BundleWiringDTO.NodeDTO> wirings

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.

57.9.6.3 public FrameworkWiringDTO()

57.10 org.osgi.resource.dto

Version 1.0

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)"

57.10.1 Summary

57.10.2 public class CapabilityDTO
extends DTO

Data Transfer Object for a Capability.

Not Thread-safe

57.10.2.1 public Map<String, Object> attributes

The attributes for the capability.

The value type must be a numerical type, Boolean, String, DTO or an array of any of the former.

Capability.getAttributes()

57.10.2.2 public Map<String, String> directives

The directives for the capability.

Capability.getDirectives()

57.10.2.3 public int id

The unique identifier of the capability.

This identifier is transiently assigned and may vary across restarts.

57.10.2.4 public String namespace

The namespace for the capability.

Capability.getNamespace()

57.10.2.5 public int resource

The identifier of the resource declaring the capability.

ResourceDTO.id, Capability.getResource()

57.10.2.6 public CapabilityDTO()

57.10.3 public class CapabilityRefDTO
extends DTO

Data Transfer Object for a reference to a Capability.

Not Thread-safe

57.10.3.1 public int capability

The identifier of the capability in the resource.

CapabilityDTO.id

57.10.3.2 public int resource

The identifier of the resource declaring the capability.

ResourceDTO.id

57.10.3.3 public CapabilityRefDTO()

57.10.4 public class RequirementDTO
extends DTO

Data Transfer Object for a Requirement.

Not Thread-safe

57.10.4.1 public Map<String, Object> attributes

The attributes for the requirement.

The value type must be a numerical type, Boolean, String, DTO or an array of any of the former.

Requirement.getAttributes()

57.10.4.2 public Map<String, String> directives

The directives for the requirement.

Requirement.getDirectives()

57.10.4.3 public int id

The unique identifier of the requirement.

This identifier is transiently assigned and may vary across restarts.

57.10.4.4 public String namespace

The namespace for the requirement.

Requirement.getNamespace()

57.10.4.5 public int resource

The identifier of the resource declaring the requirement.

ResourceDTO.id, Requirement.getResource()

57.10.4.6 public RequirementDTO()

57.10.5 public class RequirementRefDTO
extends DTO

Data Transfer Object for a reference to a Requirement.

Not Thread-safe

57.10.5.1 public int requirement

The identifier of the requirement in the resource.

RequirementDTO.id

57.10.5.2 public int resource

The identifier of the resource declaring the requirement.

ResourceDTO.id

57.10.5.3 public RequirementRefDTO()

57.10.6 public class ResourceDTO
extends DTO

Data Transfer Object for a Resource.

Not Thread-safe

57.10.6.1 public List<CapabilityDTO> capabilities

The capabilities of the resource.

Resource.getCapabilities(String)

57.10.6.2 public int id

The unique identifier of the resource.

This identifier is transiently assigned and may vary across restarts.

57.10.6.3 public List<RequirementDTO> requirements

The requirements of the resource.

Resource.getRequirements(String)

57.10.6.4 public ResourceDTO()

57.10.7 public class WireDTO
extends DTO

Data Transfer Object for a Wire.

Not Thread-safe

57.10.7.1 public CapabilityRefDTO capability

Reference to the Capability for the wire.

Wire.getCapability()

57.10.7.2 public int provider

The identifier of the provider resource for the wire.

ResourceDTO.id, Wire.getProvider()

57.10.7.3 public RequirementRefDTO requirement

Reference to the Requirement for the wire.

Wire.getRequirement()

57.10.7.4 public int requirer

The identifier of the requiring resource for the wire.

ResourceDTO.id, Wire.getRequirer()

57.10.7.5 public WireDTO()

57.10.8 public class WiringDTO
extends DTO

Data Transfer Object for a Wiring node.

Not Thread-safe

57.10.8.1 public List<CapabilityRefDTO> capabilities

The references to the capabilities for the wiring node.

Wiring.getResourceCapabilities(String)

57.10.8.2 public int id

The unique identifier of the wiring node.

This identifier is transiently assigned and may vary across restarts.

57.10.8.3 public List<WireDTO> providedWires

The provided wires for the wiring node.

Wiring.getProvidedResourceWires(String)

57.10.8.4 public List<WireDTO> requiredWires

The required wires for the wiring node.

Wiring.getRequiredResourceWires(String)

57.10.8.5 public List<RequirementRefDTO> requirements

The references to the requirements for the wiring node.

Wiring.getResourceRequirements(String)

57.10.8.6 public int resource

The identifier of the resource associated with the wiring node.

ResourceDTO.id, Wiring.getResource()

57.10.8.7 public WiringDTO()

57.11 References

57.12 Changes

  • Added support for enums and Version fields in DTOs.

  • A new DTO for the complete framework wiring, FrameworkWiringDTO, is added.