OSGi 8.1.0 · org.osgi.service.wireadmin.Wire · APIdia, the JavaDoc alternative

Method Summary

Modifier and Type	Method and Description
public Class<?>[]	Returns: An array containing the list of classes understood by the Consumer service or `null` if the `Wire` is not connected, or the consumer did not register a `WireConstants#WIREADMIN_CONSUMER_FLAVORS` property or the value of the property is not of type `Class[]`. getFlavors() Return the list of data types understood by the Consumer service connected to this `Wire` object.
public Object	Returns: The last value passed though this `Wire` object or `null` if no valid values have been passed or the Consumer service has no permission. getLastValue() Return the last value sent through this `Wire` object.
public Dictionary<String, Object>	Returns: The properties for this `Wire` object. The returned `Dictionary` must be read only. getProperties() Return the wire properties for this `Wire` object.
public String[]	Returns: A list of permitted scope names or null if the Produce or Consumer service has set no scope names. getScope() Return the calculated scope of this `Wire` object.
public boolean	Returns: true if the name is listed in the permitted scope names hasScope(String The scope name name) Return true if the given name is in this `Wire` object's scope.
public boolean	Returns: `true` if both the Producer and Consumer for this `Wire` object are connected to the `Wire` object; `false` otherwise. isConnected() Return the connection state of this `Wire` object.
public boolean	Returns: `false` if this `Wire` object is invalid because it has been deleted via `WireAdmin#deleteWire(Wire)`; `true` otherwise. isValid() Return the state of this `Wire` object.
public Object	Returns: A value whose type should be one of the types returned by `getFlavors()`,`Envelope[]`, or `null` if the `Wire` object is not connected, the Producer service threw an exception, or the Producer service returned a value which is not an instance of one of the types returned by `getFlavors()`. poll() Poll for an updated value.
public void	update(Object The updated value. The value should be an instance of one of the types returned by `getFlavors()`. value) Update the value.

Method Detail

getFlavors back to summary

getFlavors	back to summary
public Class<?>[] getFlavors() Return the list of data types understood by the Consumer service connected to this `Wire` object. Note that subclasses of the classes in this list are acceptable data types as well. The list is the value of the `WireConstants#WIREADMIN_CONSUMER_FLAVORS` service property of the Consumer service object connected to this object. If no such property was registered or the type of the property value is not `Class[]`, this method must return `null`. Returns:Class<?>[] An array containing the list of classes understood by the Consumer service or `null` if the `Wire` is not connected, or the consumer did not register a `WireConstants#WIREADMIN_CONSUMER_FLAVORS` property or the value of the property is not of type `Class[]`.

public Class<?>[] getFlavors()

Return the list of data types understood by the Consumer service connected to this Wire object. Note that subclasses of the classes in this list are acceptable data types as well.

The list is the value of the WireConstants#WIREADMIN_CONSUMER_FLAVORS service property of the Consumer service object connected to this object. If no such property was registered or the type of the property value is not Class[], this method must return null.

Returns:Class<?>[]: An array containing the list of classes understood by the Consumer service or null if the Wire is not connected, or the consumer did not register a WireConstants#WIREADMIN_CONSUMER_FLAVORS property or the value of the property is not of type Class[].

getLastValue back to summary

getLastValue	back to summary
public Object getLastValue() Return the last value sent through this `Wire` object. The returned value is the most recent, valid value passed to the `update(Object)` method or returned by the `poll()` method of this object. If filtering is performed by this `Wire` object, this methods returns the last value provided by the Producer service. This value may be an `Envelope[]` when the Producer service uses scoping. If the return value is an Envelope object (or array), it must be verified that the Consumer service has the proper WirePermission to see it. Returns:Object The last value passed though this `Wire` object or `null` if no valid values have been passed or the Consumer service has no permission.

public Object getLastValue()

Return the last value sent through this Wire object.

The returned value is the most recent, valid value passed to the update(Object) method or returned by the poll() method of this object. If filtering is performed by this Wire object, this methods returns the last value provided by the Producer service. This value may be an Envelope[] when the Producer service uses scoping. If the return value is an Envelope object (or array), it must be verified that the Consumer service has the proper WirePermission to see it.

Returns:Object: The last value passed though this Wire object or null if no valid values have been passed or the Consumer service has no permission.

getProperties back to summary

getProperties	back to summary
public Dictionary<String, Object> getProperties() Return the wire properties for this `Wire` object. Returns:Dictionary<String, Object> The properties for this `Wire` object. The returned `Dictionary` must be read only.

public Dictionary<String, Object> getProperties()

Return the wire properties for this Wire object.

Returns:Dictionary<String, Object>: The properties for this Wire object. The returned Dictionary must be read only.

getScope back to summary

getScope	back to summary
public String[] getScope() Return the calculated scope of this `Wire` object. The purpose of the `Wire` object's scope is to allow a Producer and/or Consumer service to produce/consume different types over a single `Wire` object (this was deemed necessary for efficiency reasons). Both the Consumer service and the Producer service must set an array of scope names (their scope) with the service registration property `WIREADMIN_PRODUCER_SCOPE`, or `WIREADMIN_CONSUMER_SCOPE` when they can produce multiple types. If a Producer service can produce different types, it should set this property to the array of scope names it can produce, the Consumer service must set the array of scope names it can consume. The scope of a `Wire` object is defined as the intersection of permitted scope names of the Producer service and Consumer service. If neither the Consumer, or the Producer service registers scope names with its service registration, then the `Wire` object's scope must be `null`. The `Wire` object's scope must not change when a Producer or Consumer services modifies its scope. A scope name is permitted for a Producer service when the registering bundle has `WirePermission[name,PRODUCE]`, and for a Consumer service when the registering bundle has `WirePermission[name,CONSUME]`. If either Consumer service or Producer service has not set a `WIREADMIN_*_SCOPE` property, then the returned value must be `null`. If the scope is set, the `Wire` object must enforce the scope names when `Envelope` objects are used as a parameter to update or returned from the `poll` method. The `Wire` object must then remove all `Envelope` objects with a scope name that is not permitted. Returns:String[] A list of permitted scope names or null if the Produce or Consumer service has set no scope names.

public String[] getScope()

Return the calculated scope of this Wire object. The purpose of the Wire object's scope is to allow a Producer and/or Consumer service to produce/consume different types over a single Wire object (this was deemed necessary for efficiency reasons). Both the Consumer service and the Producer service must set an array of scope names (their scope) with the service registration property WIREADMIN_PRODUCER_SCOPE, or WIREADMIN_CONSUMER_SCOPE when they can produce multiple types. If a Producer service can produce different types, it should set this property to the array of scope names it can produce, the Consumer service must set the array of scope names it can consume. The scope of a Wire object is defined as the intersection of permitted scope names of the Producer service and Consumer service.

If neither the Consumer, or the Producer service registers scope names with its service registration, then the Wire object's scope must be null.

The Wire object's scope must not change when a Producer or Consumer services modifies its scope.

A scope name is permitted for a Producer service when the registering bundle has WirePermission[name,PRODUCE], and for a Consumer service when the registering bundle has WirePermission[name,CONSUME].

If either Consumer service or Producer service has not set a WIREADMIN_*_SCOPE property, then the returned value must be null.

If the scope is set, the Wire object must enforce the scope names when Envelope objects are used as a parameter to update or returned from the poll method. The Wire object must then remove all Envelope objects with a scope name that is not permitted.

Returns:String[]: A list of permitted scope names or null if the Produce or Consumer service has set no scope names.

hasScope back to summary

hasScope	back to summary
public boolean hasScope(String name) Return true if the given name is in this `Wire` object's scope. Parameters name:String The scope name Returns:boolean true if the name is listed in the permitted scope names

public boolean hasScope(String name)

Return true if the given name is in this Wire object's scope.

Parameters

name:String: The scope name

Returns:boolean

true if the name is listed in the permitted scope names

isConnected back to summary

isConnected	back to summary
public boolean isConnected() Return the connection state of this `Wire` object. A `Wire` is connected after the Wire Admin service receives notification that the Producer service and the Consumer service for this `Wire` object are both registered. This method will return `true` prior to notifying the Producer and Consumer services via calls to their respective `consumersConnected` and `producersConnected` methods. A `WireAdminEvent` of type `WireAdminEvent#WIRE_CONNECTED` must be broadcast by the Wire Admin service when the `Wire` becomes connected. A `Wire` object is disconnected when either the Consumer or Producer service is unregistered or the `Wire` object is deleted. A `WireAdminEvent` of type `WireAdminEvent#WIRE_DISCONNECTED` must be broadcast by the Wire Admin service when the `Wire` becomes disconnected. Returns:boolean `true` if both the Producer and Consumer for this `Wire` object are connected to the `Wire` object; `false` otherwise.

public boolean isConnected()

Return the connection state of this Wire object.

A Wire is connected after the Wire Admin service receives notification that the Producer service and the Consumer service for this Wire object are both registered. This method will return true prior to notifying the Producer and Consumer services via calls to their respective consumersConnected and producersConnected methods.

A WireAdminEvent of type WireAdminEvent#WIRE_CONNECTED must be broadcast by the Wire Admin service when the Wire becomes connected.

A Wire object is disconnected when either the Consumer or Producer service is unregistered or the Wire object is deleted.

A WireAdminEvent of type WireAdminEvent#WIRE_DISCONNECTED must be broadcast by the Wire Admin service when the Wire becomes disconnected.

Returns:boolean: true if both the Producer and Consumer for this Wire object are connected to the Wire object; false otherwise.

isValid back to summary

isValid	back to summary
public boolean isValid() Return the state of this `Wire` object. A connected `Wire` must always be disconnected before becoming invalid. Returns:boolean `false` if this `Wire` object is invalid because it has been deleted via `WireAdmin#deleteWire(Wire)`; `true` otherwise.

public boolean isValid()

Return the state of this Wire object.

A connected Wire must always be disconnected before becoming invalid.

Returns:boolean: false if this Wire object is invalid because it has been deleted via WireAdmin#deleteWire(Wire); true otherwise.

poll back to summary

poll	back to summary
public Object poll() Poll for an updated value. This methods is normally called by the Consumer service to request an updated value from the Producer service connected to this `Wire` object. This `Wire` object will call the `Producer#polled(Wire)` method to obtain an updated value. If this `Wire` object is not connected, then the Producer service must not be called. If this `Wire` object has a scope, then this method must return an array of `Envelope` objects. The objects returned must match the scope of this object. The `Wire` object must remove all `Envelope` objects with a scope name that is not in the `Wire` object's scope. Thus, the list of objects returned must only contain `Envelope` objects with a permitted scope name. If the array becomes empty, `null` must be returned. A `WireAdminEvent` of type `WireAdminEvent#WIRE_TRACE` must be broadcast by the Wire Admin service after the Producer service has been successfully called. Returns:Object A value whose type should be one of the types returned by `getFlavors()`,`Envelope[]`, or `null` if the `Wire` object is not connected, the Producer service threw an exception, or the Producer service returned a value which is not an instance of one of the types returned by `getFlavors()`.

public Object poll()

Poll for an updated value.

This methods is normally called by the Consumer service to request an updated value from the Producer service connected to this Wire object. This Wire object will call the Producer#polled(Wire) method to obtain an updated value. If this Wire object is not connected, then the Producer service must not be called.

If this Wire object has a scope, then this method must return an array of Envelope objects. The objects returned must match the scope of this object. The Wire object must remove all Envelope objects with a scope name that is not in the Wire object's scope. Thus, the list of objects returned must only contain Envelope objects with a permitted scope name. If the array becomes empty, null must be returned.

A WireAdminEvent of type WireAdminEvent#WIRE_TRACE must be broadcast by the Wire Admin service after the Producer service has been successfully called.

Returns:Object: A value whose type should be one of the types returned by getFlavors(),Envelope[], or null if the Wire object is not connected, the Producer service threw an exception, or the Producer service returned a value which is not an instance of one of the types returned by getFlavors().

update back to summary

update	back to summary
public void update(Object value) Update the value. This methods is called by the Producer service to notify the Consumer service connected to this `Wire` object of an updated value. If the properties of this `Wire` object contain a `WireConstants#WIREADMIN_FILTER` property, then filtering is performed. If the Producer service connected to this `Wire` object was registered with the service property `WireConstants#WIREADMIN_PRODUCER_FILTERS`, the Producer service will perform the filtering according to the rules specified for the filter. Otherwise, this `Wire` object will perform the filtering of the value. If no filtering is done, or the filter indicates the updated value should be delivered to the Consumer service, then this `Wire` object must call the `Consumer#updated(Wire, Object)` method with the updated value. If this `Wire` object is not connected, then the Consumer service must not be called and the value is ignored. If the value is an `Envelope` object, and the scope name is not permitted, then the `Wire` object must ignore this call and not transfer the object to the Consumer service. A `WireAdminEvent` of type `WireAdminEvent#WIRE_TRACE` must be broadcast by the Wire Admin service after the Consumer service has been successfully called. Parameters value:Object The updated value. The value should be an instance of one of the types returned by `getFlavors()`. See Also `WireConstants#WIREADMIN_FILTER`

public void update(Object value)

Update the value.

This methods is called by the Producer service to notify the Consumer service connected to this Wire object of an updated value.

If the properties of this Wire object contain a WireConstants#WIREADMIN_FILTER property, then filtering is performed. If the Producer service connected to this Wire object was registered with the service property WireConstants#WIREADMIN_PRODUCER_FILTERS, the Producer service will perform the filtering according to the rules specified for the filter. Otherwise, this Wire object will perform the filtering of the value.

If no filtering is done, or the filter indicates the updated value should be delivered to the Consumer service, then this Wire object must call the Consumer#updated(Wire, Object) method with the updated value. If this Wire object is not connected, then the Consumer service must not be called and the value is ignored.

If the value is an Envelope object, and the scope name is not permitted, then the Wire object must ignore this call and not transfer the object to the Consumer service.

A WireAdminEvent of type WireAdminEvent#WIRE_TRACE must be broadcast by the Wire Admin service after the Consumer service has been successfully called.

Parameters

value:Object: The updated value. The value should be an instance of one of the types returned by getFlavors().

See Also

WireConstants#WIREADMIN_FILTER

public Interface Wire

Method Summary

Method Detail