About com.ms.object

This package provides classes and interfaces for implementing data transfer operations.

Overview

Many of the classes and interfaces in the com.ms.object package are designed to facilitate data transfer. The Transfer, TransferSession, and MetaObject interfaces and the Category class define the basic protocol for data transfer. The ObjectBag and SimpleTransferSession classes provide default implementations for commonly used interfaces.

During data transfer, a data recipient obtains a TransferSession and acts upon it. The recipient might, for example, interrogate the session to determine the types of transfers supported (by using the getAvailableEffects and getPreferredEffects methods). The recipient might also ask the session for the data being transferred (by using the getTransferData method). The data is represented in the form of a MetaObject, which can also be interrogated to determine what forms the transferred data can take.

The com.ms.object package also contains classes and interfaces that allow Java components to obtain a system service. For instance, a Java component that is hosted inside a Microsoft® ActiveX® container might want to obtain the ActiveXControlServices system service. To obtain a system service, a Java component that implements the ISiteable interface could query for and obtain an ISite object. This site object could then be queried for the service using the IServiceObjectProvider.queryService method. If the requested service is not available, a ServiceNotFoundException is thrown.

Examples

The recipient might want to support transfer of text in HTML format if it is available and fall back to plain text if HTML is not available. The following example illustrates how to interrogate the MetaObject to determine whether HTML is supported.

class Recipient
{
   Category htmlCategory = new Category("text/html");
   Category plainCategory = new Category("text/plain");

   // This method interrogates a MetaObject for data transfer.
   public void interrogate(MetaObject data)
   {
     try
     {
        Class streamClass = Class.forName("java.io.InputStream");
        if (data.hasObject(htmlCategory, streamClass))
        {
          InputStream stream = data.getObject(htmlCategory, 
                                              streamClass);
          // Do something with HTML stream.
        }
        else if (data.hasObject(plainCategory, streamClass))
        {
          InputStream stream = data.getObject(plainCategory,
                                              streamClass);
          // Do something with plain text stream.
        }
     }
     catch(ClassNotFoundException e)
     {
     }       
   }
}

For recipients that support many formats, it might be more efficient to enumerate the formats supported by the MetaObject. Using this technique, a recipient can determine possible actions based on the types of data that are offered.

class Recipient
{
   Category htmlCategory = new Category("text/html");
   Category plainCategeory = new Category ("text/plain");

   // The recipient may keep private flags to track what can
   // be done with the data.
   private static final int HAS_HTML = 1;
   private static final int HAS_TEXT = 2;

   // This method determines the values of the HAS_HTML 
   // and HAS_TEXT flags based on the data being offered.
   public int interrogate(MetaObject data)
   {
     private int avail = 0;
        
     try
     {
        Class streamClass = Class.forName("java.io.InputStream");
        Enumeration categories = data.objectCategories();
        if (categories != null)
        {
          while (categories.hasMoreElements())
          {
             Category category = (Category)categories.nextElement();
             if (category.equals(htmlCategory))
                avail |= HAS_HTML;
             else if (category.equals(plainCategory))
                avail |= HAS_TEXT;
          }
        }
     }
     catch (ClassNotFoundException e)
     {
     }

     return avail;
  }
}

Classes

Class Category

This class provides an abstract type identity.

Class ObjectBag

This class is a default implementation of the MetaObject interface that can be used to implement delayed rendering.

Class ServiceNotFoundException

This class represents an exception indicating that a requested service was not available.

Class SimpleTransferSession

This class is a default implementation of the TransferSession interface.

Interfaces

Interface IServiceObjectProvider

This interface defines a method used to request a service from an object.

Interface ISite

This interface defines the removeSiteable method, which is called when an ISiteable object detaches itself from a site.

Interface ISiteable

This interface defines methods that set and retrieve the ISite object that is associated with an ISiteable object.

Interface MetaObject

This interface defines an abstraction for an object that has multiple identities.

Interface Transfer

This interface provides constants that represent transfer effects.

Interface TransferSession

This interface defines a data transfer session abstraction that is used to describe a transfer operation.

Hierarchy

Object
  |
  +--ObjectBag (MetaObject)
  |
  +--SimpleTransferSession (TransferSession)
  |
  +--Category

Exception
  |
  +--ServiceNotFoundException

TransferSession
Transfer
IServiceObjectProvider
ISite
ISiteable
MetaObject