Introspecting instances

iPOJO provides mechanisms to introspect and reconfigure instances. Those features are available from the instance description. Currently, only the reconfiguration of primitive instances is supported.

Getting instance descriptions

There is two way to get the instance description: By using the architecture service exposed by an instance providing introspection support. By calling the getInstanceDescription() method on a ComponentInstance object (that you create thanks to a Factory)

/**
 * Returns the instance description.
 * @return the instance description of the current instance
 */
InstanceDescription getInstanceDescription();

Introspecting primitive instances

Once you get the object, cast it in (be sure that it is really a primitive instance). Then, you have access to every primitive instance aspects:

 

/**
 * Gets the list of object created by the described instance.
 * @return the created objects.
 */
public String[] getCreatedObjects() {
    ...
}

/**
 * Gets the instance service dependencies.
 * @return the set of dependency description or an empty array if
 * no dependencies.
 */
public DependencyDescription[] getDependencies() {
    ...
}

/**
 * Gets the instance service dependency matching with the given service specification or id.
 * @param specification the service specification of the looked specification.
 * @return the dependency description matching with the given service specification or id.
 * <code>null</code> is not found.
 * no dependencies.
 */
public DependencyDescription getDependency(String specification) {
    ...
}

/**
 * Gets the instance provided service matching with the given service specification.
 * @param specification the provided specification of the looked provided service.
 * @return the provided service description matching with the given service specification.
 * <code>null</code> is not found.
 */
public ProvidedServiceDescription getProvidedService(String specification) {
    ...
}

/**
 * Gets the instance provided service.
 * @return the set of provided service description or an empty array if
 * no provided services.
 */
public ProvidedServiceDescription[] getProvidedServices() {
    ...
}

/**
 * Gets the instance properties.
 * @return the set of property descriptions or an empty array if
 * no properties.
 */
public PropertyDescription[] getProperties() {
    ...
}

Manipulating dependencies

You can get service dependencies from the PrimitiveInstanceDescription. Once you get the dependency (DependencyDescription object that you want to manipulate you can call one of those method on it:

public boolean isMultiple() { ... }

public boolean isOptional() { ... }

public String getFilter() { ... }

public String getInterface() { ... }

public int getState() { ... }

public String getId() { ... }

public boolean supportsNullable() { ... }

public String getDefaultImplementation() { ... }

public int getPolicy() { ... }

public String getComparator() { ... }

public boolean isFrozen() { ... }

/**
 * Gets the service reference list.
 * @return the list of matching service reference,
 * <code>null</code> if no service reference.
 */
public List getServiceReferences() { ... }

/**
 * Gets the service reference if only one service reference is used.
 * @return the ServiceReference (only if the cardinality could be 1),
 * or <code>null</code> if no service reference.
 */
public ServiceReference getServiceReference() { ... }

/**
 * Gets the used service set.
 * @return the list [service reference]() containing the used services,
 * <code>null</code> if no providers are used
 */
public List getUsedServices() { ... }

/**
 * Sets the dependency comparator.
 * The reference set will be sort at the next usage.
 * @param cmp the comparator
 */
public void setComparator(Comparator cmp) { ... }

/**
 * Sets the dependency filter.
 * @param filter the new LDAP filter
 */
public void setFilter(Filter filter) { ... }

/**
 * Sets the dependency cardinality.
 * @param isAgg if <code>true</code> sets the dependency to aggregate,
 * if <code>false</code> sets the dependency to scalar.
 */
public void setAggregate(boolean isAgg) { ... }

/**
 * Sets the dependency optionality.
 * @param isOpt if <code>true</code> sets the dependency to optional,
 * if <code>false</code> sets the dependency to mandatory.
 */
public void setOptional(boolean isOpt) { ... }

/**
 * Gets the required service specification name.
 * @return the required service specification class name.
 */
public String getSpecification() { ... }

These methods allows getting the dependency state as well as reconfiguring the dependency by setting a new filter...

There is a slightly difference between the getServiceReference(s) methods and the getUsedServices method. The first ones returns the list of matching provider. The second one returns the list of currently used providers.

Manipulating provided services

You also can manipulate provided services .

/**
 * Gets the list of provided service specifications.
 * @return the provided contract name.
 */
public String[] getServiceSpecifications() { ... }

/**
 * Gets the list of properties.
 * A copy of the actual property set is returned.
 * @return the properties.
 */
public Properties getProperties() { ... }

/**
 * Adds and Updates service properties.
 * Existing properties are updated. 
 * New ones are added.
 * @param props the new properties
 */
public void addProperties(Dictionary props) { ... }

/**
 * Removes service properties.
 * @param props the properties to remove
 */
public void removeProperties(Dictionary props) { ...  }

/**
 * Gets provided service state.
 * @return the state of the provided service (UNREGISTERED | REGISTRED).
 */
public int getState() { ... }

/**
 * Gets the service reference.
 * @return the service reference (null if the service is unregistered).
 */
public ServiceReference getServiceReference() { ... }

/**
 * Gets the 'main' service object.
 * @return the 'main' service object or <code>null</code>
 * if no service object are created.
 */
public Object getService() { ... }

public Object[] getServices() { ... }

Thanks to these method, you can get service objects, get the registered services, and manipulate service properties.

Manipulating configuration properties

The last think that you can do from the PrimitiveInstanceDescription is to get configuration properties (PropertyDescription).

/**
 * Gets the current property name.
 * @return the property name.
 */
public String getName() { ... }

/**
 * Gets the current property type.
 * @return the property type.
 */
public String getType() { ... }

/**
 * Gets the current property value.
 * @return the default value for the property,
 * <code>null</code> if the property hasn't a value..
 */
public String getValue() { ... }

/**
 * Sets the property value.
 * This method can only be called on 'living' property
 * (properties with a {@link Property} object).
 * @param value the new value.
 */
public void setValue(Object value) { ... }

With these methods you can get a property object and update its value dynamically.