Collections and Containers

From Apache OpenOffice Wiki
Jump to: navigation, search



Collections and containers are concepts for objects that contain multiple sub-objects where the number of sub-objects is usually not predetermined. While the term collection is used when the sub-objects are implicitly determined by the collection itself, the term container is used when it is possible to add new sub-objects and remove existing sub-objects explicitly. Thus, containers add methods like insert() and remove() to the collection interfaces.

In general, the Apache OpenOffice API collection and container interfaces contain any type that can be represented by the UNO type any. However, many container instances can be bound to a specific type or subtypes of this type. This is a runtime and specification agreement, and cannot be checked at runtime.

The base interface for collections is com.sun.star.container.XElementAccess that determines the types of the sub-object, if they are determined by the collection, and the number of contained sub-objects. Based on XElementAccess, there are three main types of collection interfaces:

com.sun.star.container.XIndexAccess is extended by com.sun.star.container.XIndexReplace to replace existing sub-objects by index, and com.sun.star.container.XIndexContainer to insert and remove sub-objects. You can find the same similarity for com.sun.star.container.XNameAccess and other specific collection types.

All containers support com.sun.star.container.XContainer that has interfaces to register com.sun.star.container.XContainerListener interfaces. This way it is possible for an application to learn about insertion and removal of sub-objects in and from the container.

Documentation note.png The com.sun.star.container.XIndexAccess is appealing to programmers because in most cases, it is easy to implement. But this interface should only be implemented if the collection really is indexed.

Refer to the module com.sun.star.container in the API reference for details about collection and container interfaces.

The following examples demonstrate the usage of the three main collection interfaces. First, we iterate through an indexed collection. The index always starts with 0 and is continuous:

  // get an XIndexAccess interface from the collection
  XIndexAccess xIndexAccess = (XIndexAccess) UnoRuntime.queryInterface(
      XIndexAccess.class, mxCollection);
 
  // iterate through the collection by index
  int i;
  for (i = 0; i < xIndexAccess.getCount(); ++i) {
      Object aSheet = xIndexAccess.getByIndex(i);
      Named xSheetNamed = (XNamed) UnoRuntime.queryInterface(XNamed.class, aSheet);
      System.out.println("sheet #" + i + " is named '" + xSheetNamed.getName() + "'");
  }

Our next example iterates through a collection with named objects. The element names are unique within the collection and case-sensitive.

  // get an XNameAccess interface from the collection
  XNameAccess xNameAccess = (XNameAccess) UnoRuntime.queryInterface(XNameAccess.class, mxCollection);
 
  // get the list of names
  String[] aNames = xNameAccess.getElementNames();
 
  // iterate through the collection by name
  int i;
  for (i = 0; i < aNames.length; ++i) {
      // get the i-th object as a UNO Any
      Object aSheet = xNameAccess.getByName( aNames[i] );
 
      // get the name of the sheet from its XNamed interface
      XNamed xSheetNamed = (XNamed) UnoRuntime.queryInterface(XNamed.class, aSheet);
      System.out.println("sheet '" + aNames[i] + "' is #" + i);
  }

The next example shows how we iterate through a collection using an enumerator. The order of the enumeration is undefined. It is only defined that all elements are enumerated. The behavior is undefined, if the collection is modified after creation of the enumerator.

  // get an XEnumerationAccess interface from the collection
  XEnumerationAccess xEnumerationAccess = (XEnumerationAccess) UnoRuntime.queryInterface(
      XEnumerationAccess.class, mxCollection );
 
  // create an enumerator
  XEnumeration xEnum = xEnumerationAccess.createEnumeration();
 
  // iterate through the collection by name
  while (xEnum.hasMoreElements()) {
      // get the next element as a UNO Any
      Object aSheet = xEnum.nextElement();
 
      // get the name of the sheet from its XNamed interface
      XNamed xSheetNamed = (XNamed) UnoRuntime.queryInterface(XNamed.class, aSheet);
      System.out.println("sheet '" + xSheetNamed.getName() + "'");
  }

For an example showing the use of containers, see Styles where a new style is added into the style family ParagraphStyles.

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages