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)
          For internal use only
 void addClientDocumentEventListener(IClientDocumentEventListener listener)
          For internal use only
 void close()
           Closes the ReportClientDocument and releases all resources.
abstract  java.lang.String displayName()
           Returns the title of the document.
 void dispose()
           For internal use only.
 boolean getIsModified()
          Returns true if the document has been modified, and false otherwise.
 java.util.Locale getLocale()
          Deprecated. Replaced by ClientDocument.getProductLocale(). See also ClientDocument.getPreferredViewingLocale().
 java.util.Locale getPreferredViewingLocale()
          Gets the locale used to render the report.
 java.util.Locale getProductLocale()
          Gets the locale of the application user interface and error messages.
 java.lang.String getReportAppServer()
           Returns the name of the RAS server being used.
 ReportAppSession getReportAppSession()
           Returns the session connection to the RAS server.
 java.util.TimeZone getTimeZone()
           
 IUndoManager getUndoManager()
           
 void initialize(ReportAppSession appSession)
           For internal use only.
 void initServerAgent(boolean fDueToAgentTimedOut)
           For internal use only.
abstract  boolean isReadOnly()
           Returns true if this document is read-only, false otherwise.
 boolean isReadyToDispose()
           Internal use only.
 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 postCloseServerAgent()
           For internal use only.
 void postCreateServerAgent(boolean fDueToAgentTimedOut)
           For internal use only.
 void preCloseServerAgent()
           For internal use only.
 void preCreateServerAgent(boolean fDueToAgentTimedOut)
           For internal use only.
 void removeAdvancedClientDocumentEventListener(IAdvancedClientDocumentEventListener listener)
          For internal use only
 void removeClientDocumentEventListener(IClientDocumentEventListener listener)
          For internal use only.
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)
          Deprecated.  
 void setPreferredViewingLocale(java.util.Locale preferredViewingLocale)
           Sets the preferred viewing locale of the report.
 void setProductLocale(java.util.Locale productLocale)
           Sets the product locale of the report.
 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.
 void uninitServerAgent()
           For internal use only.
 
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)
For internal use only


addAdvancedClientDocumentEventListener

public void addAdvancedClientDocumentEventListener(IAdvancedClientDocumentEventListener listener)
For internal use only


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

dispose

public void dispose()

For internal use only.


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

@Deprecated
public java.util.Locale getLocale()
Deprecated. Replaced by ClientDocument.getProductLocale(). See also ClientDocument.getPreferredViewingLocale().

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

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

getProductLocale

public java.util.Locale getProductLocale()
Gets the locale of the application user interface and error messages.

Returns:
The application interface locale.
See Also:
ClientDocument.getPreferredViewingLocale()

getPreferredViewingLocale

public java.util.Locale getPreferredViewingLocale()
Gets the locale used to render the report.

Returns:
The report viewing locale.
See Also:
ClientDocument.getProductLocale()

getTimeZone

public java.util.TimeZone getTimeZone()

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:
ClientDocument.setReportAppServer(java.lang.String)

getReportAppSession

public ReportAppSession getReportAppSession()

Returns the session connection to the RAS server.

When you use RAS in SAP BusinessObjects Enterprise, 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 the SAP BusinessObjects Enterprise server group management capabilities.

Returns:
A ReportAppSession object containing the session connection to the RAS server.
See Also:
ClientDocument.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:
ClientDocument.setReportAppSession(com.crystaldecisions.sdk.occa.report.application.ReportAppSession)

initServerAgent

public void initServerAgent(boolean fDueToAgentTimedOut)
                     throws ReportSDKException

For internal use only.

Throws:
ReportSDKException

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

isReadyToDispose

public boolean isReadyToDispose()

Internal use only.


newDocument

public void newDocument()
                 throws ReportSDKException

Creates a new, empty document.

Note: This method is used in the standalone version of RAS. It is not used with SAP Business Objects Enterprise. To create a new document, use the IReportAppFactory interface in the SAP 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. To open a report document using the RAS server in the SAP BusinessObjects Enterprise environment, use the IReportAppFactory interface in the SAP BusinessObjects Enterprise Java SDK.

If you are running the add-in to SAP 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 SAP BusinessObjects Enterprise. 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 SAP BusinessObjects Enterprise. For information on applying processing extensions to a report, see the SAP 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

postCloseServerAgent

public void postCloseServerAgent()

For internal use only.


postCreateServerAgent

public void postCreateServerAgent(boolean fDueToAgentTimedOut)

For internal use only.


preCloseServerAgent

public void preCloseServerAgent()

For internal use only.


preCreateServerAgent

public void preCreateServerAgent(boolean fDueToAgentTimedOut)

For internal use only.


removeClientDocumentEventListener

public void removeClientDocumentEventListener(IClientDocumentEventListener listener)
For internal use only.


removeAdvancedClientDocumentEventListener

public void removeAdvancedClientDocumentEventListener(IAdvancedClientDocumentEventListener listener)
For internal use only


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 ClientDocument.isReadOnly() method to check if the file is read-only or not.

If the report contains processing extensions and if it is saved to SAP BusinessObjects Enterprise, the processing extensions are saved with the report. For information on applying processing extensions to a report, see the SAP 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 ClientDocument.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 SAP 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, 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 SAP 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 SAP 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
Deprecated. 

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

Note: This method is only used in standalone RAS. When you use RAS in SAP BusinessObjects Enterprise, 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

setProductLocale

public void setProductLocale(java.util.Locale productLocale)
                      throws ReportSDKException

Sets the product locale of the report. The product locale is the locale of the user interface (UI) of the components such as the viewers that display the report to the user.

The product locale controls the user interface (UI) for the viewers and related components (parameter prompt dialog box, toolbar, error messages) when displaying a report to the user. To change the regional formatting of dates, times, and numbers in the report, see the ClientDocument.setPreferredViewingLocale(java.util.Locale preferredViewingLocale) method.

Parameters:
productLocale - A java.util.Locale object as the locale.
Throws:
ReportSDKException

setPreferredViewingLocale

public void setPreferredViewingLocale(java.util.Locale preferredViewingLocale)
                               throws ReportSDKException

Sets the preferred viewing locale of the report. The preferred viewing locale is the locale that a user would prefer to see data presented in.

The preferred viewing locale controls regional formatting of dates, times, and numbers in the report. To change the locale of the user interface (UI) for the viewers and related components (parameter prompt dialog, toolbar, error messages) when displaying a report to the user, see the ClientDocument.setProductLocale(java.util.Locale productLocale) method.

Parameters:
preferredViewingLocale - A java.util.Locale object as the locale.
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. 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.

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 SAP BusinessObjects Enterprise SDK.

Parameters:
reportAppServer - A String that specifies the name of the RAS server to use.
Throws:
ReportSDKException
See Also:
ClientDocument.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:
ClientDocument.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

uninitServerAgent

public void uninitServerAgent()

For internal use only.