[jira] [Updated] (CELIX-441) Add service tracker api to bundle context

["Pepijn Noltes (JIRA)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/CELIX-441?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Pepijn Noltes updated CELIX-441:
--------------------------------
    Description: 
To make the use of service trackers easier integrate a service tracker API directly on the bundle context.

The service tracker should be stored in the bundle context and automatically be closed and destroy when the bundle is respectively stopped / destroyed. 

Proposed API:

/**
 * track service for the provided serviceName and/or filter.
 * The highest ranking services will used for the callback.
 * If a new and higher ranking services the callback with be called again with the new service.
 * If a service is removed a the callback with be called with next highest ranking service or NULL as service.
 *
 * @param ctx The bundle context.
 * @param serviceName Optional the service name to track
 * @param serviceVersionRange Optional the service version range to track
 * @param filter Optional the LDAP filter to use
 * @param data The data pointer, which will be used in the callbacks
 * @param setting The callback, which will be called when a new highest ranking service is set.
 * @return the tracker uuid or null uuid (uuid_is_null) if unsuccessful.
 */
uuid_t bundleContext_trackService(
        bundle_context_t* mod,
        const char* serviceName,
        const char* serviceVersionRange,
        const char* filter,
        void* data,
        int (*setting)(void* data, void* svc)
);

/**
 * track services for the provided serviceName and/or filter.
 *
 * @param ctx The bundle context.
 * @param serviceName Optional the service name to track
 * @param serviceVersionRange Optional the service version range to track
 * @param filter Optional the LDAP filter to use
 * @param data The data pointer, which will be used in the callbacks
 * @param adding The callback, which will be called when service is added.
 * @param removing The callback, which will be called when a service is removed
 * @return the tracker uuid or null uuid (uuid_is_null) if unsuccessful.
 */
uuid_t bundleContext_trackServices(
        bundle_context_t* ctx,
        const char* serviceName,
        const char* serviceVersionRange,
        const char* filter,
        void* data,
        int (*adding)(void* data, void* svc),
        int (*removing)(void* data, void* svc)
);

typedef struct celix_service_tracker_options {
    //service filter options
    const char* serviceName;
    const char* serviceVersionRange;
    const char* filter;
    const char* lang; //NULL -> 'CELIX_LANG_C'

    //callback options
    void* callbackHandle;

    int (*onSettingFp)(void *handle, void *svc); //highest ranking
    int (*onAddingFp)(void *handle, void *svc);
    int (*onRemovingFp)(void *handle, void *svc);

    int (*onSettingWithProperties)(void *handle, properties_t *props, void *svc); //highest ranking
    int (*onAddingWithProperties)(void *handle, properties_t *props, void *svc);
    int (*onRemovingWithProperties)(void *handle, properties_t *props, void *svc);

    int (*onSettingWithOwner)(void *handle, bundle_t *owner, properties_t *props, void *svc); //highest ranking
    int (*onAddingWithOwner)(void *handle, bundle_t *owner, properties_t *props, void *svc);
    int (*onRemovingWithOwner)(void *handle, bundle_t *owner, properties_t *props, void *svc);
} celix_service_tracker_options;

/**
 * Tracks services using the provided tracker options.
 * The tracker options are only using during this call and can safely be freed/reused after this call returns.
 *
 * @param ctx The module context.
 * @param opts The pointer to the tracker options.
 * @return the tracker uuid or null uuid (uuid_is_null) if unsuccessful.
 */
uint64_t bundleContext_trackServicesWithOptions(bundle_context_t *ctx, const celix_service_tracker_options *opts);

//shortcut could be const celix_service_tracker_options opts = {0};

/**
 * Stop the tracker with the provided track id.
 * Only works for the trackers owned by the bundle of the bundle context.
 *
 * @return CELIX_SUCCESS if the tracker is stopped correctly.
 */
int bundleContext_stopTracking(bundle_context_t *ctx, uuid_t trackerId); [^bundle_context_additions.h] 

  was:
To make the use of service trackers easier integrate a service tracker API directly on the bundle context.

The service tracker should be stored in the bundle context and automatically be closed and destroy when the bundle is respectively stopped / destroyed. 

Proposed API:

/**
 * track service for the provided serviceName and/or filter.
 * The highest ranking services will used for the callback.
 * If a new and higher ranking services the callback with be called again with the new service.
 * If a service is removed a the callback with be called with next highest ranking service or NULL as service.
 *
 * @param ctx The bundle context.
 * @param serviceName Optional the service name to track
 * @param serviceVersionRange Optional the service version range to track
 * @param filter Optional the LDAP filter to use
 * @param data The data pointer, which will be used in the callbacks
 * @param setting The callback, which will be called when a new highest ranking service is set.
 * @return the tracker uuid or null uuid (uuid_is_null) if unsuccessful.
 */
uuid_t bundleContext_trackService(
        bundle_context_t* mod,
        const char* serviceName,
        const char* serviceVersionRange,
        const char* filter,
        void* data,
        int (*setting)(void* data, void* svc)
);

/**
 * track services for the provided serviceName and/or filter.
 *
 * @param ctx The bundle context.
 * @param serviceName Optional the service name to track
 * @param serviceVersionRange Optional the service version range to track
 * @param filter Optional the LDAP filter to use
 * @param data The data pointer, which will be used in the callbacks
 * @param adding The callback, which will be called when service is added.
 * @param removing The callback, which will be called when a service is removed
 * @return the tracker uuid or null uuid (uuid_is_null) if unsuccessful.
 */
uuid_t bundleContext_trackServices(
        bundle_context_t* ctx,
        const char* serviceName,
        const char* serviceVersionRange,
        const char* filter,
        void* data,
        int (*adding)(void* data, void* svc),
        int (*removing)(void* data, void* svc)
);

typedef struct celix_service_tracker_options {
    //service filter options
    const char* serviceName;
    const char* serviceVersionRange;
    const char* filter;
    const char* lang; //NULL -> 'CELIX_LANG_C'

    //callback options
    void* callbackHandle;

    int (*onSettingFp)(void *handle, void *svc); //highest ranking
    int (*onAddingFp)(void *handle, void *svc);
    int (*onRemovingFp)(void *handle, void *svc);

    int (*onSettingWithProperties)(void *handle, properties_t *props, void *svc); //highest ranking
    int (*onAddingWithProperties)(void *handle, properties_t *props, void *svc);
    int (*onRemovingWithProperties)(void *handle, properties_t *props, void *svc);

    int (*onSettingWithOwner)(void *handle, bundle_t *owner, properties_t *props, void *svc); //highest ranking
    int (*onAddingWithOwner)(void *handle, bundle_t *owner, properties_t *props, void *svc);
    int (*onRemovingWithOwner)(void *handle, bundle_t *owner, properties_t *props, void *svc);
} celix_service_tracker_options;

/**
 * Tracks services using the provided tracker options.
 * The tracker options are only using during this call and can safely be freed/reused after this call returns.
 *
 * @param ctx The module context.
 * @param opts The pointer to the tracker options.
 * @return the tracker uuid or null uuid (uuid_is_null) if unsuccessful.
 */
uint64_t bundleContext_trackServicesWithOptions(bundle_context_t *ctx, const celix_service_tracker_options *opts);

//shortcut could be const celix_service_tracker_options opts = {0};

/**
 * Stop the tracker with the provided track id.
 * Only works for the trackers owned by the bundle of the bundle context.
 *
 * @return CELIX_SUCCESS if the tracker is stopped correctly.
 */
int bundleContext_stopTracking(bundle_context_t *ctx, uuid_t trackerId);


> Add service tracker api to bundle context
> -----------------------------------------
>
>                 Key: CELIX-441
>                 URL: https://issues.apache.org/jira/browse/CELIX-441
>             Project: Celix
>          Issue Type: Improvement
>          Components: Framework
>    Affects Versions: 2.3.0
>            Reporter: Pepijn Noltes
>            Priority: Major
>         Attachments: bundle_context_additions.h
>
>
> To make the use of service trackers easier integrate a service tracker API directly on the bundle context.
> The service tracker should be stored in the bundle context and automatically be closed and destroy when the bundle is respectively stopped / destroyed. 
> Proposed API:
> /**
>  * track service for the provided serviceName and/or filter.
>  * The highest ranking services will used for the callback.
>  * If a new and higher ranking services the callback with be called again with the new service.
>  * If a service is removed a the callback with be called with next highest ranking service or NULL as service.
>  *
>  * @param ctx The bundle context.
>  * @param serviceName Optional the service name to track
>  * @param serviceVersionRange Optional the service version range to track
>  * @param filter Optional the LDAP filter to use
>  * @param data The data pointer, which will be used in the callbacks
>  * @param setting The callback, which will be called when a new highest ranking service is set.
>  * @return the tracker uuid or null uuid (uuid_is_null) if unsuccessful.
>  */
> uuid_t bundleContext_trackService(
>         bundle_context_t* mod,
>         const char* serviceName,
>         const char* serviceVersionRange,
>         const char* filter,
>         void* data,
>         int (*setting)(void* data, void* svc)
> );
> /**
>  * track services for the provided serviceName and/or filter.
>  *
>  * @param ctx The bundle context.
>  * @param serviceName Optional the service name to track
>  * @param serviceVersionRange Optional the service version range to track
>  * @param filter Optional the LDAP filter to use
>  * @param data The data pointer, which will be used in the callbacks
>  * @param adding The callback, which will be called when service is added.
>  * @param removing The callback, which will be called when a service is removed
>  * @return the tracker uuid or null uuid (uuid_is_null) if unsuccessful.
>  */
> uuid_t bundleContext_trackServices(
>         bundle_context_t* ctx,
>         const char* serviceName,
>         const char* serviceVersionRange,
>         const char* filter,
>         void* data,
>         int (*adding)(void* data, void* svc),
>         int (*removing)(void* data, void* svc)
> );
> typedef struct celix_service_tracker_options {
>     //service filter options
>     const char* serviceName;
>     const char* serviceVersionRange;
>     const char* filter;
>     const char* lang; //NULL -> 'CELIX_LANG_C'
>     //callback options
>     void* callbackHandle;
>     int (*onSettingFp)(void *handle, void *svc); //highest ranking
>     int (*onAddingFp)(void *handle, void *svc);
>     int (*onRemovingFp)(void *handle, void *svc);
>     int (*onSettingWithProperties)(void *handle, properties_t *props, void *svc); //highest ranking
>     int (*onAddingWithProperties)(void *handle, properties_t *props, void *svc);
>     int (*onRemovingWithProperties)(void *handle, properties_t *props, void *svc);
>     int (*onSettingWithOwner)(void *handle, bundle_t *owner, properties_t *props, void *svc); //highest ranking
>     int (*onAddingWithOwner)(void *handle, bundle_t *owner, properties_t *props, void *svc);
>     int (*onRemovingWithOwner)(void *handle, bundle_t *owner, properties_t *props, void *svc);
> } celix_service_tracker_options;
> /**
>  * Tracks services using the provided tracker options.
>  * The tracker options are only using during this call and can safely be freed/reused after this call returns.
>  *
>  * @param ctx The module context.
>  * @param opts The pointer to the tracker options.
>  * @return the tracker uuid or null uuid (uuid_is_null) if unsuccessful.
>  */
> uint64_t bundleContext_trackServicesWithOptions(bundle_context_t *ctx, const celix_service_tracker_options *opts);
> //shortcut could be const celix_service_tracker_options opts = {0};
> /**
>  * Stop the tracker with the provided track id.
>  * Only works for the trackers owned by the bundle of the bundle context.
>  *
>  * @return CELIX_SUCCESS if the tracker is stopped correctly.
>  */
> int bundleContext_stopTracking(bundle_context_t *ctx, uuid_t trackerId); [^bundle_context_additions.h] 



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)