org.eclipse.datatools.connectivity.oda.design.ui.designsession
Class DataSourceDesignSession

java.lang.Object
  extended by org.eclipse.datatools.connectivity.oda.design.internal.designsession.DataSourceDesignSessionBase
      extended by org.eclipse.datatools.connectivity.oda.design.ui.designsession.DataSourceDesignSession

public class DataSourceDesignSession
extends org.eclipse.datatools.connectivity.oda.design.internal.designsession.DataSourceDesignSessionBase

An UI design session for use by an ODA host designer to interact and communicate with custom ODA UI extensions to create or edit an extended ODA data source design instance.


Nested Class Summary
static interface DataSourceDesignSession.IDesignNameValidator
          The public interface for call-back to an ODA design name validator provided by an ODA consumer application to validate the name of a data source design defined in the ODA connection profile selection page.
static class DataSourceDesignSession.ProfileReference
          Represents the reference information of an external connection profile.
 
Nested classes/interfaces inherited from class org.eclipse.datatools.connectivity.oda.design.internal.designsession.DataSourceDesignSessionBase
org.eclipse.datatools.connectivity.oda.design.internal.designsession.DataSourceDesignSessionBase.IDesignNameValidatorBase, org.eclipse.datatools.connectivity.oda.design.internal.designsession.DataSourceDesignSessionBase.ProfileReferenceBase
 
Method Summary
 OdaDesignSession cancel()
          Performs cancel on this design session.
static OdaDesignSession convertDesignToLinkedProfile(DesignSessionRequest request, java.lang.String newProfileBaseName, boolean useProfileInDesign, boolean promptCreateProfileStore, org.eclipse.swt.widgets.Shell parentShell)
          Converts the data source design, in the specified DesignSessionRequest, to export its connection properties to a new connection profile instance, and optionally links to it.
static OdaDesignSession createNewDesignFromProfile(java.lang.String odaDataSourceId, java.lang.String newDataSourceName, DataSourceDesignSession.ProfileReference profileRef)
          Creates a design session with a new data source design, whose properties and their values are copied from, or referenced to, the given profile reference.
 OdaDesignSession finish()
          Performs finish on this design session to create or edit its data source design.
 org.eclipse.ui.dialogs.PropertyPage getEditorPage()
          Returns a customized editor page for use within a design session to edit an extended ODA data source design instance.
 org.eclipse.core.runtime.IAdaptable getEditPropertyPageElement()
          Returns a customized editor page's adaptable element that represents the the extended ODA data source design instance that is being edited.
 org.eclipse.jface.wizard.IWizard getNewWizard()
          Returns an ODA wizard for use within this design session to create a new, extended ODA data source design instance.
 org.eclipse.ui.dialogs.PropertyPage getProfileSelectionPropertyPage()
          Returns the property page that allows an user to update the selection of a connection profile.
 DesignSessionRequest getRequest()
          Returns the session request that has started this design session.
 org.eclipse.jface.wizard.IWizardPage getWizardStartingPage()
          Returns a customized starting wizard page for use within this design session to create a new, extended ODA data source design instance.
 void restartNewDesign(java.lang.String odaDataSourceId, java.lang.String newDataSourceName, DataSourceDesignSession.ProfileReference profileRef, DesignSessionRequest request)
          Restarts the design session to create a new data source design instance with the given name for the given ODA data source type, and initializes with the properties specified in the given profile instance.
 boolean setAndVerifyUseProfileSelectionPage()
           
 void setDesignNameValidator(DataSourceDesignSession.IDesignNameValidator validator)
          Assigns the specified design name validator to the wizard page that collects user input of a design name.
 void setUseProfileSelectionPage(boolean use)
           
static DataSourceDesignSession startEditDesign(DesignSessionRequest request)
          Requests to start a design session to edit a data source design, as specified in the given ODA design session request.
static DataSourceDesignSession startEditDesign(DesignSessionRequest request, DataSourceEditorPage editorPage)
          Requests to start a design session with the given editor page to edit a data source design, as specified in the given ODA design session request.
static DataSourceDesignSession startNewDesign(java.lang.String odaDataSourceId, java.lang.String newDataSourceName)
          Starts a design session to create a new data source design instance with the given name for the given ODA data source type.
static DataSourceDesignSession startNewDesign(java.lang.String odaDataSourceId, java.lang.String newDataSourceName, DataSourceDesignSession.ProfileReference profileRef, DesignSessionRequest request)
          Starts a design session to create a new data source design instance with the given name for the given ODA data source type, and initializes with the properties specified in the given profile instance.
static DataSourceDesignSession startNewDesignFromProfile()
          Starts a design session to create a new data source design instance, whose properties and their values are copied from, or referenced to, the given profile instance reference.
 
Methods inherited from class org.eclipse.datatools.connectivity.oda.design.internal.designsession.DataSourceDesignSessionBase
getNewCustomOdaStartingPage
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

startNewDesign

public static DataSourceDesignSession startNewDesign(java.lang.String odaDataSourceId,
                                                     java.lang.String newDataSourceName)
                                              throws OdaException
Starts a design session to create a new data source design instance with the given name for the given ODA data source type.
This method supports a simplified request for an editable session in the default system locale.

Parameters:
odaDataSourceId - an ODA data source extension element id
newDataSourceName - a unique name that identifies a data source design instance
Returns:
a started design session, ready to create a new data source design
Throws:
OdaException
See Also:
startNewDesign(String, String, ProfileReference, DesignSessionRequest)

startNewDesign

public static DataSourceDesignSession startNewDesign(java.lang.String odaDataSourceId,
                                                     java.lang.String newDataSourceName,
                                                     DataSourceDesignSession.ProfileReference profileRef,
                                                     DesignSessionRequest request)
                                              throws OdaException
Starts a design session to create a new data source design instance with the given name for the given ODA data source type, and initializes with the properties specified in the given profile instance.

Parameters:
odaDataSourceId - an ODA data source extension element id
newDataSourceName - a unique name that identifies a data source design instance
profileRef - optional reference to an existing profile instance kept in an external profile storage file; may be null if no reference to an existing profile
request - optional design session request specification, such as session's edit state and locale; may be null for an editable session in the default system locale
Returns:
a started design session, ready to create a new data source design
Throws:
OdaException

startNewDesignFromProfile

public static DataSourceDesignSession startNewDesignFromProfile()
Starts a design session to create a new data source design instance, whose properties and their values are copied from, or referenced to, the given profile instance reference.
This method should be used when an ODA host designer wants to use the DTP ODA Profile Selection UI page for an user to select a connection profile instance.

Returns:
a started design session, ready to create a new data source design
Since:
3.0.4

restartNewDesign

public void restartNewDesign(java.lang.String odaDataSourceId,
                             java.lang.String newDataSourceName,
                             DataSourceDesignSession.ProfileReference profileRef,
                             DesignSessionRequest request)
                      throws OdaException
Restarts the design session to create a new data source design instance with the given name for the given ODA data source type, and initializes with the properties specified in the given profile instance.
Restarting a design session on the same ODA data source type would preserve any user edits made on the session's custom wizard page.

Parameters:
odaDataSourceId -
newDataSourceName -
profileRef -
request -
Throws:
OdaException
See Also:
startNewDesign(String, String, ProfileReference, DesignSessionRequest)

startEditDesign

public static DataSourceDesignSession startEditDesign(DesignSessionRequest request)
                                               throws OdaException
Requests to start a design session to edit a data source design, as specified in the given ODA design session request.
This is responsible for creating a custom editor page instance for use to edit a data source design.

Parameters:
request - a design session request, must contain a data source design to edit
Returns:
a started design session, ready to edit the requested data source design
Throws:
OdaException
See Also:
startEditDesign(DesignSessionRequest, DataSourceEditorPage)

startEditDesign

public static DataSourceDesignSession startEditDesign(DesignSessionRequest request,
                                                      DataSourceEditorPage editorPage)
                                               throws OdaException
Requests to start a design session with the given editor page to edit a data source design, as specified in the given ODA design session request.

Parameters:
request - a design session request, must contain a data source design to edit
editorPage - the property page instance created by the ODA host to edit the design; may be null, in which case the session will create a custom page
Returns:
a started design session, ready to edit the requested data source design
Throws:
OdaException

createNewDesignFromProfile

public static OdaDesignSession createNewDesignFromProfile(java.lang.String odaDataSourceId,
                                                          java.lang.String newDataSourceName,
                                                          DataSourceDesignSession.ProfileReference profileRef)
                                                   throws OdaException
Creates a design session with a new data source design, whose properties and their values are copied from, or referenced to, the given profile reference.
This method should be used when an ODA host designer wants to finish a design session right away after a profile is selected, and skips using its custom wizard page.
A completed response contains the new or updated data source design instance, and the designer state.

Parameters:
odaDataSourceId - an ODA data source extension element id
newDataSourceName - unique name to assign to new data source instance; may be null or empty, in which case the profile name is applied
profileRef - reference to an existing profile instance kept in an external profile storage file
Returns:
a completed design session with the session response, containing the new data source design, and the original request.
Throws:
OdaException

convertDesignToLinkedProfile

public static OdaDesignSession convertDesignToLinkedProfile(DesignSessionRequest request,
                                                            java.lang.String newProfileBaseName,
                                                            boolean useProfileInDesign,
                                                            boolean promptCreateProfileStore,
                                                            org.eclipse.swt.widgets.Shell parentShell)
                                                     throws OdaException
Converts the data source design, in the specified DesignSessionRequest, to export its connection properties to a new connection profile instance, and optionally links to it.
The exported connection profile would persist in the default profile storage used by the DTP Data Source Explorer. In addition, caller may optionally trigger prompting users whether to copy the exported profile to a separate connection profile store file.

Parameters:
request - a design session request, must contain a valid data source design to convert from
newProfileBaseName - optional suggested base name of the new connection profile; may be null or empty to use the same name as that of the data source design. If the suggested name is already used by an existing profile in the default repository, an unique name will be generated with a number appended to the base name.
useProfileInDesign - indicates whether to update the data source design to link to the exported profile
promptCreateProfileStore - indicates whether to prompt users to create a separate connection profile store
parentShell - the parent shell for the UI dialog to create profile store; must not be null if promptCreateProfileStore is true
Returns:
the completed design session containing a session response with the converted data source design
Throws:
OdaException - if the conversion task failed; if the data source design in the specified request is already linked to a connection profile, the cause of thrown exception is an IllegalArgumentException
Since:
3.2 (DTP 1.7)

getRequest

public DesignSessionRequest getRequest()
Returns the session request that has started this design session. May return null if none was used to start this design session.

Overrides:
getRequest in class org.eclipse.datatools.connectivity.oda.design.internal.designsession.DataSourceDesignSessionBase
Returns:
the design session request, which may specify the original data source design to edit

finish

public OdaDesignSession finish()
                        throws OdaException
Performs finish on this design session to create or edit its data source design. This then gathers the data source definition collected in custom UI designer, and maps into a session response with a new or updated data source design instance.
This method must be called only after the corresponding wizard or editor has performed finish.
Returns a completed design session with a session response that contains a new or updated data source design instance, and the designer state.

Overrides:
finish in class org.eclipse.datatools.connectivity.oda.design.internal.designsession.DataSourceDesignSessionBase
Returns:
a completed ODA design with the session response and the original request, if any.
Throws:
OdaException

cancel

public OdaDesignSession cancel()
Performs cancel on this design session. The design session is then cancelled and contains session response with a user_cancelled state.

Overrides:
cancel in class org.eclipse.datatools.connectivity.oda.design.internal.designsession.DataSourceDesignSessionBase
Returns:
the completed design session containing a session response with a user_cancelled state

setUseProfileSelectionPage

public void setUseProfileSelectionPage(boolean use)
Overrides:
setUseProfileSelectionPage in class org.eclipse.datatools.connectivity.oda.design.internal.designsession.DataSourceDesignSessionBase

setAndVerifyUseProfileSelectionPage

public boolean setAndVerifyUseProfileSelectionPage()
Overrides:
setAndVerifyUseProfileSelectionPage in class org.eclipse.datatools.connectivity.oda.design.internal.designsession.DataSourceDesignSessionBase

setDesignNameValidator

public void setDesignNameValidator(DataSourceDesignSession.IDesignNameValidator validator)
Assigns the specified design name validator to the wizard page that collects user input of a design name.

Parameters:
validator - interface for a call-back validator
Since:
3.0.4

getNewWizard

public org.eclipse.jface.wizard.IWizard getNewWizard()
                                              throws OdaException
Returns an ODA wizard for use within this design session to create a new, extended ODA data source design instance.

Overrides:
getNewWizard in class org.eclipse.datatools.connectivity.oda.design.internal.designsession.DataSourceDesignSessionBase
Returns:
a wizard instance to embed in a wizard dialog for use within this started design session
Throws:
OdaException

getWizardStartingPage

public org.eclipse.jface.wizard.IWizardPage getWizardStartingPage()
                                                           throws OdaException
Returns a customized starting wizard page for use within this design session to create a new, extended ODA data source design instance.

Overrides:
getWizardStartingPage in class org.eclipse.datatools.connectivity.oda.design.internal.designsession.DataSourceDesignSessionBase
Returns:
a customized wizard page to add in a wizard for use within this started design session
Throws:
OdaException

getProfileSelectionPropertyPage

public org.eclipse.ui.dialogs.PropertyPage getProfileSelectionPropertyPage()
                                                                    throws OdaException
Returns the property page that allows an user to update the selection of a connection profile.

Returns:
a PropertyPage for use in a PreferenceDialog
Throws:
OdaException
Since:
3.0.4

getEditorPage

public org.eclipse.ui.dialogs.PropertyPage getEditorPage()
                                                  throws OdaException
Returns a customized editor page for use within a design session to edit an extended ODA data source design instance.

Overrides:
getEditorPage in class org.eclipse.datatools.connectivity.oda.design.internal.designsession.DataSourceDesignSessionBase
Returns:
a customized property page
Throws:
OdaException

getEditPropertyPageElement

public org.eclipse.core.runtime.IAdaptable getEditPropertyPageElement()
                                                               throws OdaException
Returns a customized editor page's adaptable element that represents the the extended ODA data source design instance that is being edited.

Overrides:
getEditPropertyPageElement in class org.eclipse.datatools.connectivity.oda.design.internal.designsession.DataSourceDesignSessionBase
Returns:
Throws:
OdaException