# The discovery package

The `org.sblim.cimclient.discovery` package offers high-level discovery functions for WBEM services. The design point behind it was to provide an API that is protocol agnostic and hides the nasty details of the discovery protocol and the advertisement format.

With the following code snippet you can discover all WBEM services using the SLP DA "da.foo.net":

    String[] directoryAgents = new String[] {"da.foo.net"};
    Discoverer discoverer = DiscovererFactory.getDiscoverer(DiscovererFactory.SLP);
    WBEMServiceAdvertisement[] advertisements = discoverer.findWbemServices(directoryAgents);

The factory pattern allows support for discovery protocols other than SLP in the future. However, SLP is the only supported one today. The `WBEMServiceAdvertisement` interface provides the means to easily retrieve all the information from the WBEM template:

    String url = advertisements[0].getServiceUrl();
    String id = advertisements[0].getServiceId();
    String[] ns = advertisements[0].getInteropNamespaces();
    String name = advertisements[0].getAttribute(WBEMServiceAdvertisement.SERVICE_HI_NAME);

You may also create a `WBEMClient` directly from the `WBEMServiceAdvertisement`:

    Subject subject = new Subject(); // in real life you would need real credentials ... of course
    WBEMClient client = advertisements[0].createClient(subject, Locale.getAvailableLocales());

Last but not least we have the `AdvertisementCatalog` class. It helps managing the discovered advertisements by addressing common issues:

- The same service registers with multiple URLs (e.g. for HTTP and HTTPS) and/or multiple directories. The `AdvertisementCatalog` groups advertisements by service-id and lets you select the appropriate one by your protocol preference.

    WBEMProtocol[] protocols = new WBEMProtocol[3];
    protocols[0] = new WBEMProtocol("https", "cim-xml");
    protocols[2] = new WBEMProtocol("http", "cim-xml");

    String[] directoryAgents = new String[] {"da.foo.net"};
    Discoverer discoverer = DiscovererFactory.getDiscoverer(DiscovererFactory.SLP);
    WBEMServiceAdvertisement[] advertisements = discoverer.findWbemServices(directoryAgents);
    AdvertisementCatalog catalog = new AdvertisementCatalog();
    catalog.addAdvertisements(advertisements);

    String[] ids = catalog.getKnownIds();
    for(String id : ids) {
       WBEMServiceAdvertisement adv = catalog.getAdvertisement(id, protocols);
       WBEMClient client = adv.createClient(subject, Locale.getAvailableLocales());
    }

- The list of advertisements changes over time, items appear and disappear. The `AdvertisementCatalog` offers listener interfaces which are notified when items are added, removed, expired or renewed.

      AdvertisementCatalog cat = new AdvertisementCatalog();
      final AdvertisementCatalog.EventListener listener =
        new AdvertisementCatalog.EventListener() {
          public void advertisementEvent(int pEvent, WBEMServiceAdvertisement pAdvertisment) {
            switch (pEvent) {
              case AdvertisementCatalog.EVENT_ADD:
                   /* handle event */
                   break;
              case AdvertisementCatalog.EVENT_REMOVE:
                   /* handle event */
                   break;
              case AdvertisementCatalog.EVENT_EXPIRE:
                   /* handle event */
                   break;
              case AdvertisementCatalog.EVENT_RENEW:
                    /* handle event */
                    break;
              default:
            }
          }
        };
      catalog.addEventListener(listener);
      Discoverer dsc = DiscovererFactory.getDiscoverer(DiscovererFactory.SLP);
      ...
      String[] directoryAgents = new String[] {"da.foo.net"};
      WBEMServiceAdvertisement[] advs = dsc.findWbemServices(directoryAgents);
      cat.refreshAdvertisements(directoryAgents, advs);