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

    java.lang.Object
      org.eclipse.datatools.connectivity.oda.design.internal.designsession.DataSourceDesignSessionBase
          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`