Skip to main content
Blackboard Help

Using the API and Determining Relationships

When using the API, there are specific steps than need to be followed to determine the relationships between the entity and the persistence classes.

How to Determine Relationships

  1. The program must first initialize the BbServiceManager object. The method call is blackboard.platform.BbServiceManager.init( serviceConfig ); where serviceConfig is a object. This object represents a link to the configuration file on the operating system. The file is a detailed list of all services that are active on the instance of the servicemanager as well as any of their configuration files.

    The BbServiceManager object is only initialized once for each execution of the application.

    A virtual host is also needed for proper setup. A virtual host can be obtained by first getting the Virtual Installation Manager using BBServiceManager.lookupService(VirtualInstallationManager.class). The Virtual Installation Manager has a getVirtualHost(String id) method which returns the virtual host.

    Next, the ContextManager must be retrieved using BBServiceManager.lookupService(ContextManager.class).  Finally, the context can be set by calling the ContextManager’s setContext() method and passing in the virtual host as an argument.

    The following code sample assumes a “SERVICE_CONFIG_DIR” and “VIRTUAL_HOST_KEY” properties will be set, probably through –D parameters if it is used in a command line application.  The SERVICE_CONFIG_DIR should be set to the full path of the Blackboard config directory, while the VIRTUAL_HOST_KEY needs to be the virtual installation you want to test, by default it is bb_bb60.

    // Initialize the BbServiceManager and set the context

    Follow the steps below to determine the relationships between the entity and persistence classes.
          blackboard.platform.BbServiceManager.init(System.getProperties().getProperty("SERVICE_CONFIG_DIR") + "");
          // The virtual host is needed to establish the proper database context.
          VirtualInstallationManager vm = (VirtualInstallationManager)
          String vhostUID = System.getProperty("VIRTUAL_HOST_KEY", "bb_bb60");
          VirtualHost vhost = vm.getVirtualHost(vhostUID);
          vhost = vm.getVirtualHost(vhostUID);
          if(vhost == null)
            throw new Exception("Virtual Host '" + vhostUID + "' not found.");
          // Now that the vhost is set we can set the context based on that vhost
          ContextManager cm = (ContextManager) BbServiceManager.lookupService(ContextManager.class);
          Context context = cm.setContext(vhost);
        catch(Exception e)
          System.out.println("Exception trying to init the BbPersistenceManager\n " + e.toString() + "..exiting.\n");

  2. The controller creates an entity object and sets its attributes.
  3. The following is an example of how to get a Course site: site=new;

  4. The controller requests a persist action off the Loader / Persister.

    CourseSiteLoader cLoader=
    CourseSitePersister cPersister=

  5. The controller catches any persistence exceptions that occur.

Repeat steps 2, 3, and 4 as needed for different entities and different persist actions.