Documents

From Apache OpenOffice Wiki
Jump to: navigation, search



Reading a Document Content

A UCB content that is a document, that is, the value of the required property IsDocument is true, supports the command "open". The command takes an argument of type com.sun.star.ucb.OpenCommandArgument2. Note that this command with the same argument type is also used to access the children of a folder. As seen in the examples, the argument's Mode member controls access to the children or the data stream, or both for contents that support both. If you are interested in the data stream, ignore the command's return value, which will presumably be a null value.

The caller must implement a data sink and supply this implementation as "open" command arguments to get access to the data stream of a document. These data sinks are called back by the implementation when the "open" command is executed. There are two different interfaces for data sinks to choose from, com.sun.star.io.XActiveDataSink and com.sun.star.io.XOutputStream.

  • XActiveDataSink: If this type of data sink is supplied, the caller of the command is active. It consists of the following methods:
  void setInputStream( [in] com::sun::star::io::XInputStream aStream)
  com::sun::star::io::XInputStream getInputStream()

The implementation of the command supplies an implementation of the interface com.sun.star.io.XInputStream to the given data sink using setInputStream() and return. Once the execute-call has returned, the caller accesses the input stream calling getInputStream() and read the data using that stream, through readBytes() or readSomeBytes().

  • XOutputStream: If this type of data sink is supplied, the caller of the command is passive. The data sink is called back through the following methods of XOutputStream:
  void writeBytes( [in] sequence< byte > aData) 
  void closeOutput()
  void flush()

The implementation of the command writes all data to the output stream calling writeBytes() and closes it through closeOutput() after all data was successfully written. Only then will the open command return.

The type to use depends on the logic of the client application. If the application is designed so that it passively processes the data supplied by an com.sun.star.io.XOutputStream using an output stream as sink is advantageous, because many content providers implement this case efficiently without buffering any data. If the application is designed so that it actively reads the data, use an com.sun.star.io.XActiveDataSink, then any necessary buffering takes place in the implementation of the open command.

The following example shows a possible implementation of an com.sun.star.io.XActiveDataSink and its usage with the "open" command:

  import com.sun.star.io.XActiveDataSink;
  import com.sun.star.io.XInputStream;
 
  /////////////////////////////////////////////////////////////////////////
  // XActiveDataSink interface implementation.
  /////////////////////////////////////////////////////////////////////////
 
  public class MyActiveDataSink implements XActiveDataSink {
      XInputStream m_aStream = null;
 
      public MyActiveDataSink() {
          super();
      }
 
      public void setInputStream(XInputStream aStream) {
          m_aStream = aStream;
      }
 
      public XInputStream getInputStream() {
          return m_aStream;
      }
  };

Now this data sink implementation can be used with the "open" command. After opening the document content, getInputStream() returns the input stream containing the document data. The actual byte content is read using readSomeBytes() in the following fragment:

  import com.sun.star.ucb.*;
  import ...MyActiveDataSink;
 
  {
      XContent xContent = ...
 
      /////////////////////////////////////////////////////////////////////
      // Read the document data stream of a document content using a
      // XActiveDataSink implementation as data sink....
      /////////////////////////////////////////////////////////////////////
      // Fill argument structure...
 
      OpenCommandArgument2 aArg = new OpenCommandArgument2;
      aArg.Mode = OpenMode.DOCUMENT;
      aArg.Priority = 32768;// Ignored by most implementations
 
      // Create data sink implementation object.
      XActiveDataSink xDataSink = new MyActiveDataSink;
      aArg.Sink = xDataSink;
 
      try {
          // Execute command "open". The implementation of the command will
          // supply an XInputStream implementation to the data sink,
          // using helper method executeCommand (see [[Documentation/DevGuide/UCB/Executing Content Commands|Executing Content Commands]])
          executeCommand(xContent, "open", aArg);
      }
      catch (com.sun.star.ucb.CommandAbortedException e) {
          ... error ...
      }
      catch (com.sun.star.uno.Exception e) {
          ... error ...
      }
 
      // Get input stream supplied by the open command implementation.
      XInputStream xData = xDataSink.getInputStream();
      if (xData == null)
          ... error ...
 
      /////////////////////////////////////////////////////////////////////
      // Read data from input stream...
      /////////////////////////////////////////////////////////////////////
      try {
          // Data buffer. Will be allocated by input stream implementation!
          byte[][] aBuffer = new byte[1][1];
 
          int nRead = xData.readSomeBytes(aBuffer, 65536);
          while (nRead > 0) {
              // Process data contained in buffer.
              ...
 
              nRead = xData.readSomeBytes(aBuffer, 65536);
          }
 
          // EOF.
      }
      catch (com.sun.star.io.NotConnectedException e) {
          ... error ...
      }
      catch (com.sun.star.io.BufferSizeExceededException e) {
          ... error ...
      }
      catch (com.sun.star.io.IOException e) {
          ... error ...
      }
  }

Storing a Document Content

A UCB content that is a document, that is, the value of the required property IsDocument is true, supports the command "insert". This command is used to overwrite the document's data stream. The command requires an argument of type com.sun.star.ucb.InsertCommandArgument and returns void. The caller supplies the implementation of an com.sun.star.io.XInputStream with the command argument. This stream contains the data to be written. An additional flag indicating if an existing content and its data should be overwritten is supplied with the command argument. Implementations that are not able to detect if there are previous data may ignore this parameter and will always write the new data.

Setting or storing the content data stream of a UCB document content is shown below:

  import com.sun.star.ucb.*;
  import com.sun.star.io.XInputStream;
 
  {
      XContent xContent = ...
      XInputStream xData = ... // The data to write.
 
      /////////////////////////////////////////////////////////////////////
      // Write the document data stream of a document content...
      /////////////////////////////////////////////////////////////////////
 
      // Fill argument structure...
 
      InsertCommandArgument aArg = new InsertCommandArgument();
      aArg.Data = xData;
      aArg.ReplaceExisting = true;
 
      try {
          // Execute command "insert".
          // using helper method executeCommand (see [CHAPTER:UCB.Using.Commands]).
          executeCommand(xContent, "insert", aArg);
      }
      catch (com.sun.star.ucb.CommandAbortedException e) {
          ... error ...
      }
      catch (com.sun.star.uno.Exception e) {
          ... error ...
      }
  }
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages