com.crystaldecisions.sdk.occa.report.application
Class ClientDocument

java.lang.Object
  extended by com.crystaldecisions.sdk.occa.report.application.ClientDocument
Direct Known Subclasses:
ReportClientDocument

public abstract class ClientDocument
extends java.lang.Object

This abstract class represents a general Report Application Server document. ClientDocument is used as a base class to support methods and properties that are common to all Report Application Server documents. Currently, only the Crystal Report document type is supported. The ReportClientDocument object (represents a report) is derived from the ClientDocument class.


Field Summary
static java.lang.String URIPROTOCAL_CECUID
           
static java.lang.String URIPROTOCAL_CEIS
           
static java.lang.String URIPROTOCAL_RAS
           
static java.lang.String URIPROTOCAL_RASSDK
           
 
Constructor Summary
ClientDocument()
           
ClientDocument(IEnterprisePlugin plugin)
           
 
Method Summary
 void addAdvancedClientDocumentEventListener(IAdvancedClientDocumentEventListener listener)
           
 void addClientDocumentEventListener(IClientDocumentEventListener listener)
           
 void close()
           Closes the ReportClientDocument and releases all resources.
abstract  java.lang.String displayName()
           Returns the title of the document.
 boolean getIsModified()
          Returns true if the document has been modified, and false otherwise.
 java.util.Locale getLocale()
           Returns the locale that is used to localize various aspects of the document.
 java.lang.String getReportAppServer()
           Returns the name of the RAS server being used.
 ReportAppSession getReportAppSession()
           Returns the session connection to the RAS server.
 IUndoManager getUndoManager()
           
 void initialize(ReportAppSession appSession)
           For internal use only.
abstract  boolean isReadOnly()
           Returns true if this document is read-only, false otherwise.
 void newDocument()
           Creates a new, empty document.
 void open(java.lang.Object documentPath, int options)
           Opens a supported document.
abstract  java.lang.String path()
           Returns the full path of the document.
 void removeAdvancedClientDocumentEventListener(IAdvancedClientDocumentEventListener listener)
           
 void removeClientDocumentEventListener(IClientDocumentEventListener listener)
           
abstract  void save()
           Saves changes to the current document.
abstract  void saveAs(java.lang.String displayName, java.lang.Object parentFolderPath, int options)
           Saves changes to a new document.
 void setIsModifiedUntilSaved()
          For internal use only.
 void setLocale(java.util.Locale locale)
           Sets the locale that is used to localize various aspects of the document.
 void setReportAppServer(java.lang.String reportAppServer)
           Sets the RAS server to be used.
 void setReportAppSession(ReportAppSession appSession)
           Sets the session connection to the RAS server.
 void setTimeZone(java.util.TimeZone timeZone)
           
abstract  PropertyBag UID()
           Returns the properties that uniquely identify this ClientDocument object.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

URIPROTOCAL_RAS

public static final java.lang.String URIPROTOCAL_RAS
See Also:
Constant Field Values

URIPROTOCAL_RASSDK

public static final java.lang.String URIPROTOCAL_RASSDK
See Also:
Constant Field Values

URIPROTOCAL_CEIS

public static final java.lang.String URIPROTOCAL_CEIS
See Also:
Constant Field Values

URIPROTOCAL_CECUID

public static final java.lang.String URIPROTOCAL_CECUID
See Also:
Constant Field Values
Constructor Detail

ClientDocument

public ClientDocument()

ClientDocument

public ClientDocument(IEnterprisePlugin plugin)
Method Detail

addClientDocumentEventListener

public void addClientDocumentEventListener(IClientDocumentEventListener listener)

addAdvancedClientDocumentEventListener

public void addAdvancedClientDocumentEventListener(IAdvancedClientDocumentEventListener listener)

close

public void close()
           throws ReportSDKException

Closes the ReportClientDocument and releases all resources.

NOTE: This method must be called by the user. This is important because of how memory is handled on the RAS server. When a ReportClientDocument instance goes out of scope and is garbage-collected, the report behind the ReportClientDocument instance, which was opened on the RAS server, is not closed. The report can no longer be accessed, but it remains in memory on the RAS server until the server is shut down.

Throws:
ReportSDKException

displayName

public abstract java.lang.String displayName()
                                      throws ReportSDKException

Returns the title of the document.

Returns:
A String containing the document's title.
Throws:
ReportSDKException

getIsModified

public boolean getIsModified()
                      throws ReportSDKException
Returns true if the document has been modified, and false otherwise.

Returns:
true if the document has been modified, and false otherwise.
Throws:
ReportSDKException

getLocale

public java.util.Locale getLocale()

Returns the locale that is used to localize various aspects of the document.

Returns:
The Locale object.
See Also:
setLocale(java.util.Locale)

getReportAppServer

public java.lang.String getReportAppServer()

Returns the name of the RAS server being used.

Returns:
A String that specifies the name of the Report Application Server being used.
See Also:
setReportAppServer(java.lang.String)

getReportAppSession

public ReportAppSession getReportAppSession()

Returns the session connection to the RAS server.

When you use RAS in Crystal Enterprise 9.0 or higher (BusinessObjects Enterprise as of version 11), you should not get the ReportAppSession from a ClientDocument object and use it to create or open another document. If you do so, your application will not take advantage of BusinessObjects Enterprise server group management capabilities.

Returns:
A ReportAppSession object containing the session connection to the RAS server.
See Also:
setReportAppSession(com.crystaldecisions.sdk.occa.report.application.ReportAppSession)

getUndoManager

public IUndoManager getUndoManager()

initialize

public void initialize(ReportAppSession appSession)
                throws ReportSDKException

For internal use only.

Throws:
ReportSDKException
See Also:
setReportAppSession(com.crystaldecisions.sdk.occa.report.application.ReportAppSession)

isReadOnly

public abstract boolean isReadOnly()
                            throws ReportSDKException

Returns true if this document is read-only, false otherwise.

Returns:
true if this document is read-only, false otherwise.
Throws:
ReportSDKException

newDocument

public void newDocument()
                 throws ReportSDKException

Creates a new, empty document.

Note: This method is used in the standalone version of RAS, and in the RAS add-in component for Crystal Enterprise 8.x. It is not used with RAS in Crystal Enterprise 9.0 or higher (BusinessObjects Enterprise as of version 11). To create a new document, use the IReportAppFactory interface in the BusinessObjects Enterprise Java SDK.

Throws:
ReportSDKException

open

public void open(java.lang.Object documentPath,
                 int options)
          throws ReportSDKException

Opens a supported document. This method is used in the standalone version of RAS for Crystal Reports 9.0 or higher, and RAS add-in component for Crystal Enterprise 8.x. To open a report document using the RAS server in Crystal Enterprise 9.0 or higher (BusinessObjects Enterprise as of version 11), use the IReportAppFactory interface in BusinessObjects Enterprise Java SDK.

If you are running the add-in to BusinessObjects Enterprise version of RAS, you must assign a valid Enterprise session to the EnterpriseSession property of the ClientDocument object before calling this method. If you are running the standalone version of the RAS server, create and initialize a ReportAppSession object and use it to create a ClientDocument object.

If you are using the standalone version, the source of the report document can be one of the following:

If you are using the RAS server add-in for Crystal Enterprise 8.x, the source of the report document can be one of the following:

Note: This method should not be used when you are running RAS server within Crystal Enterprise 9.0 or higher (BusinessObjects Enterprise as of version 11). Instead, use the openDocument method in IReportAppFactory.

RAS provides full support for processing extensions. Processing extensions allows you to filter the data that users can see. Because RAS supports processing extensions, you are able to see the same data as if the report was opened through BusinessObjects Enterprise. For information on applying processing extensions to a report, see the BusinessObjects Enterprise Administrator's Guide.

Parameters:
documentPath - A document to be opened. This can be one of the following:
  • A URI, or path to a file
  • An Enterprise InfoObject
  • An Enterprise InfoObject ID
options - Specifies how the file should be opened. For valid options, see OpenReportOptions.
Throws:
ReportSDKException

path

public abstract java.lang.String path()
                               throws ReportSDKException

Returns the full path of the document.

Returns:
A String that specifies the full path of the document.
Throws:
ReportSDKException

removeClientDocumentEventListener

public void removeClientDocumentEventListener(IClientDocumentEventListener listener)

removeAdvancedClientDocumentEventListener

public void removeAdvancedClientDocumentEventListener(IAdvancedClientDocumentEventListener listener)

save

public abstract void save()
                   throws java.io.IOException,
                          ReportSDKException

Saves changes to the current document.

If the file cannot be modified, or is marked read-only, the method will fail. Use the isReadOnly() method to check if the file is read-only or not. Note that this method can save a file to Crystal Enterprise 9 or 10 (BusinessObjects Enterprise as of version 11) , but cannot save a file to Crystal Enterprise 8 or 8.5.

If the report contains processing extensions and if it is saved to BusinessObjects Enterprise, the processing extensions are saved with the report. For information on applying processing extensions to a report, see the BusinessObjects Enterprise Administrator's Guide.

Throws:
java.io.IOException
ReportSDKException

saveAs

public abstract void saveAs(java.lang.String displayName,
                            java.lang.Object parentFolderPath,
                            int options)
                     throws ReportSDKException,
                            java.io.IOException

Saves changes to a new document.

After the document is saved, the ClientDocument object points to the newly saved document. You cannot overwrite an existing file if it is read-only. You can use the isReadOnly() method to check if the document is read-only or not.

Parameters:
displayName - The name of the file. This parameter is required for this version.
parentFolderPath - This parameter specifies a folder where the report is saved.

If you are using a RAS server running within the BusinessObjects Enterprise framework, this parameter can be:

  • An Enterprise Folder InfoObject
  • The ID of an Enterprise Folder InfoObject (as Integer)

If you are using the standalone RAS server with Crystal Reports 9.0 or higher, this parameter is the path of a folder on a server (the RAS Server or RAS SDK machine). See the Setting up your RAS environment section in the Setting up the Development Environment chapter of the Reference Guide for details on report location.

If the report contains processing extensions and if it is saved to BusinessObjects Enterprise, the processing extensions are saved with the report. If it is saved to a folder on the RAS server or on RAS SDK machine the processing extensions are not preserved. However, the report's selection formulas are modified to apply the data filtering rules enforced by the processing extensions. For information on applying processing extensions to a report, see the BusinessObjects Enterprise Administrator's Guide.

options - Specifies how the file should be saved. For valid options, see ReportSaveAsOptions.
Throws:
ReportSDKException
java.io.IOException

setIsModifiedUntilSaved

public void setIsModifiedUntilSaved()
For internal use only.


setLocale

public void setLocale(java.util.Locale locale)
               throws ReportSDKException

Sets the locale that is used to localize various aspects of the document.

Note: This method is only used in standalone RAS for Crystal Reports 9.0 or higher, and RAS add-in component for Crystal Enterprise 8.x. When you use RAS in Crystal Enterprise 9.0 or higher (BusinessObjects Enterprise as of version 11), the locale is set when you create a a ReportClientDocument using the IReportAppFactory openDocument method. The locale cannot be set after the ReportClientDocument has been created.

Parameters:
locale - The Locale object used to localize the document.
Throws:
ReportSDKException

setTimeZone

public void setTimeZone(java.util.TimeZone timeZone)
                 throws ReportSDKException
Throws:
ReportSDKException

setReportAppServer

public void setReportAppServer(java.lang.String reportAppServer)
                        throws ReportSDKException

Sets the RAS server to be used.The ReportAppServer is also used by ConnectionDirManager to get directory items.

This method is used in the standalone RAS for Crystal Reports 9.0 or higher, and in RAS server add-in component for Crystal Enterprise 8.x. It allows you to establish a connection with a specific RAS server on the network. If this property is not set, a RAS server is selected using a round robin scheme from the servers specified in the clientSDKOptions.xml file.

When you use the RAS in Crystal Enterprise 9.0 or higher (BusinessObjects Enterprise as of version 11), a RAS server is selected according to the server selection policy set by the Administrator. The server selection policy can also be set using interfaces provided by the BusinessObjects Enterprise SDK.

Parameters:
reportAppServer - A String that specifies the name of the RAS server to use.
Throws:
ReportSDKException
See Also:
getReportAppServer()

setReportAppSession

public void setReportAppSession(ReportAppSession appSession)
                         throws ReportSDKException

Sets the session connection to the RAS server.

The ReportAppSession is set by the system when a ClientDocument object is created. This property cannot be set after the ClientDocument object has been opened.

Parameters:
appSession - A ReportAppSession object containing the session connection to the RAS server.
Throws:
ReportSDKException
See Also:
getReportAppSession()

UID

public abstract PropertyBag UID()
                         throws ReportSDKException

Returns the properties that uniquely identify this ClientDocument object.

Returns:
A PropertyBag containing the properties that uniquely identify this ClientDocument object.
Throws:
ReportSDKException