Package com.documentum.operations

# Interface IDfImportOperation

All Superinterfaces:
  `IDfOperation`

public interface IDfImportOperation extends IDfOperation
IDfImportOperation performs a complete client import of one or more nodes. This includes detecting compound file references, creating new docbase objects for top level and referenced files, uploading content files to the server, performing the initial save, and cleaning up local content files. Note that compound references to existing docbase objects (e.g. through XML links) will cause those existing objects to be checked in as part of the import operation. Note that you MUST specify a session using the setSession() method prior to adding any objects to the import operation. You should also set the destination cabinet or folder using the setDestinationFolderId() on either the operation as a whole or nodes individually. Either an IDfFile or a file path specified as a string may be added to the import operation. When importing XML content, you may specify the name of the XML application to apply to the XML content. The XML application defines the configuration rules to be applied to the XML, such as how the content will be broken out into docbase objects, the relationships between XML content chunks, etc. The automatic processing of XML content based on XML application configuration was added in DFC 4.2. Earlier versions of DFC do not have this capability. Here is one example of how to import an XML document:

>      ' Construct the operation and create a
>      ' cast to the import operation interface.
>      '
>      Dim operation As IDfOperation
>      Dim importOperation As IDfImportOperation
>      Set operation = clientX.getOperation("Import")
>      Set importOperation = operation

>      ' Establish the docbase session for the import operation to use.
>      '
>      Call importOperation.setSession(session)

>      ' Setup the file path for the file to import.
>      '
>      Dim myXMLFile As IDfFile
>      Set myXMLFile = clientX.getFile("C:\mydoc.xml")

>      ' Add the XML file to the import operation.
>      ' Create a cast to the import node interface.
>      '
>      Dim node As IDfOperationNode
>      Dim importNode As IDfImportNode
>      Set node = operation.Add(myXMLFile)
>      Set importNode = node

>      ' Specify the XML application to use in processing this XML
>      ' instance. Note, this could also be accomplished through
>      ' a processing instruction in the XML content itself.
>      '
>      Call node.setXMLApplicationName("MyXMLApplication")

>      ' Execute the operation.
>      '
>      If (operation.execute() = False) Then
>          '
>          ' Error hanlding code goes here. Use operation.getErrors() to
>          ' get an IDfList of operation errors back.
>          '
>      End If

- ## Field Summary

  ### Fields inherited from interface com.documentum.operations.IDfOperation

  `GENERATE_RESOURCE_FORK, IGNORE_RESOURCE_FORK, REQUIRE_RESOURCE_FORK, RESOURCE_FORK_UNDEFINED, USE_RESOURCE_FORK_IF_AVAILABLE`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `IDfAcsTransferPreferences`
  `getAcsTransferPreferences()`
  Returns the `IDfAcsTransferPreferences` object to be used.
  `IDfId`
  `getDestinationFolderId()`
  Returns the docbase object Id of the destination folder for the copy operation.
  `String`
  `getExternalVariable(String varName)`
  Returns the value of an external variable.
  `boolean`
  `getKeepLocalFile()`
  Returns a boolean value indicating whether or not the local content file should be preserved or deleted as part of the operation.
  `int`
  `getMacOption()`
  Returns the setting for Mac handling for this operation.
  `IDfList`
  `getNewObjects()`
  Returns the list of unique new objects created as a result of this operation.
  `IDfSession`
  `getSession()`
  Returns session to be used to import new objects.
  `String`
  `getVersionLabels()`
  Returns the symbolic version labels that will be applied when the node is checked in.
  `void`
  `setAcsTransferPreferences(IDfAcsTransferPreferences acsTransferPreferences)`
  Sets the `IDfAcsTransferPreferences` object to be used.
  `void`
  `setDestinationFolderId(IDfId destinationFolderId)`
  Sets the docbase object Id for the destination folder for the copy operation.
  `void`
  `setExternalVariable(String varName, String value)`
  Sets a variable that will be available to the XML application's configuration file as an <external_variable>.
  `void`
  `setKeepLocalFile(boolean keepFile)`
  Sets a boolean value indicating whether or not the local content file should be preserved or deleted as part of the operation.
  `void`
  `setLinkBase(String linkBase)`
  Sets the link base to be used during import operation.
  `void`
  `setMacOption(int option)`
  Sets the Mac behavior options for this operation.
  `void`
  `setSession(IDfSession importSession)`
  Sets the session that will be used to create new docbase objects.
  `void`
  `setVersionLabels(String newVersionLabels)`
  Sets the symbolic version labels that will be applied when the node is checked in.

  ### Methods inherited from interface com.documentum.operations.IDfOperation

  `abort, add, areDisabledRegistryUpdates, canUndo, disableRegistryUpdates, enablePopulateWithReferences, execute, getContext, getDescription, getErrors, getName, getNodes, getOperationMonitor, getOperationType, getProperties, getRootNodes, getSteps, isAborted, isEnabledPopulateWithReferences, logError, removeNode, reportError, resetErrors, setOperationMonitor, succeeded`

- ## Method Details

  - ### getSession

    IDfSession getSession() throws DfException
    Returns session to be used to import new objects.
    Specified by:
      `getSession` in interface `IDfOperation`
    Returns:
      session that will be used to create new docbase objects.
    Throws:
      `DfException`
    See Also:
      - `IDfSession`

  - ### setSession

    void setSession(IDfSession importSession) throws DfException
    Sets the session that will be used to create new docbase objects.
    Specified by:
      `setSession` in interface `IDfOperation`
    Parameters:
      `importSession` - session to use when importing objects.
    Throws:
      `DfException`
    See Also:
      - `IDfSession`

  - ### getVersionLabels

    String getVersionLabels() throws DfException
    Returns the symbolic version labels that will be applied when the node is checked in. These labels should NOT include any implicit version labels (e.g. 1.0).
    Returns:
      comma separated list of symbolic version labels.
    Throws:
      `DfException`
    See Also:
      - `IDfSysObject.getVersionLabel(int)`

  - ### setVersionLabels

    void setVersionLabels(String newVersionLabels) throws DfException
    Sets the symbolic version labels that will be applied when the node is checked in. These labels should NOT include any implicit version labels (e.g. 1.0).
    Parameters:
      `newVersionLabels` - comma separated list of symbolic version labels.
    Throws:
      `DfException`
    See Also:
      - `IDfSysObject.getVersionLabel(int)`

  - ### getKeepLocalFile

    boolean getKeepLocalFile() throws DfException
    Returns a boolean value indicating whether or not the local content file should be preserved or deleted as part of the operation.
    Returns:
      if true, the local content file will not be deleted as part of the operation.
    Throws:
      `DfException`

  - ### setKeepLocalFile

    void setKeepLocalFile(boolean keepFile) throws DfException
    Sets a boolean value indicating whether or not the local content file should be preserved or deleted as part of the operation.
    Parameters:
      `keepFile` - if true the local content file will not be deleted as part of the operation.
    Throws:
      `DfException`

  - ### getDestinationFolderId

    IDfId getDestinationFolderId() throws DfException
    Returns the docbase object Id of the destination folder for the copy operation. This is the folder where, by default, new objects will be created. The folder location may be overridden for individual nodes using setDestinationFolderId() of DfOperationNode.
    Returns:
      docbase Id of the default destination folder for the operation.
    Throws:
      `DfException`
    See Also:
      - `IDfFolder`

  - ### setDestinationFolderId

    void setDestinationFolderId(IDfId destinationFolderId) throws DfException
    Sets the docbase object Id for the destination folder for the copy operation. This is the folder where, by default, new objects will be created. The folder location may be overridden for individual nodes using setDestinationFolderId() of DfOperationNode.
    Parameters:
      `destinationFolderId` - - IDfId destination docbase folder / cabinet Id.
    Throws:
      `DfException`
    See Also:
      - `IDfFolder`

  - ### getNewObjects

    IDfList getNewObjects() throws DfException
    Returns the list of unique new objects created as a result of this operation. Each entry in the list is an IDfSysObject.
    Returns:
      returns the list of unique new objects created as a result of this operation.
    Throws:
      `DfException`
    See Also:
      - `IDfSysObject`

  - ### setExternalVariable

    void setExternalVariable(String varName, String value)
    Sets a variable that will be available to the XML application's configuration file as an <external_variable>.
    Here is an example of how the external variable is used in the XML configuration file:
    <external_variables>
    <external_variable>
    <name>CITY</name>
    <default>Vancouver</default>
    </external_variable>
    </external_variables>
    ...
    <metadata>
    <dctmattr>
    <name>city</name>
    <template><var name="CITY"/></template>
    </dctmattr>
    </metadata>
    If a variable is declared in the XMl configuration file, but is not set via setExternalVariable, the default value of the variable will be used.
    Parameters:
      `varName` - The name that the variable will be available as in the XMl configuration file.
      `value` - The value of the variable.

  - ### getExternalVariable

    String getExternalVariable(String varName)
    Returns the value of an external variable.
    Parameters:
      `varName` - The name of the external variable.
    Returns:
      The value of the variable.

  - ### setLinkBase

    void setLinkBase(String linkBase)
    Sets the link base to be used during import operation. During export and check out operations, user can patch external references by specifying link base and cabinet folder path in setBaseFolder() method in IDfExportOperation or IDfCheckoutOperation During import operation, when a link base is encountered in external references, DFC will ignore the link base portion (which matches the link base provided in this method) in the path and will try and identify the object corresponding to the cabinet-folder path following the link base. For e.g. assume that the content file has link path corresponding to "http://www.somecompany.com/WebsiteA/ProductABC/Images/product.jpg". During check in operation user can specify link base as "http://www.somecompany.com". The import operation processing will ignore the link base "http://www.somecompany.com" and will try to find the object corresponding to "/WebsiteA/ProductABC/Images/product.jpg" path.
    Parameters:
      `linkBase` - to be used during import operation

  - ### getMacOption

    int getMacOption()
    Returns the setting for Mac handling for this operation.

        Possible values include:
                        IGNORE_RESOURCE_FORK - No resource fork will be stored in the docbase, even
                                     if resource fork file path has been specified
                        USE_RESOURCE_FORK_IF_AVAILABLE - Resource fork will be set to the docbase if supplied
                                                by the caller of the operation
                        REQUIRE_RESOURCE_FORK - Resource fork is required. An error will be generated if
                                      resource fork is not made available.
                        GENERATE_RESOURCE_FORK - A resource fork will be generated if it is not explicitly
                                       available.

    Returns:
      the setting for Mac handling for this operation.If no mac option is set via setMacOption(), then RESOURCE_FORK_UNDEFINED will be returned.
    Since:
      DFC 5.2.5

  - ### setMacOption

    void setMacOption(int option)
    Sets the Mac behavior options for this operation. The appledouble option may be overridden for individual nodes using setMacOption of IDfImportNode.

        Possible values include:
                        IGNORE_RESOURCE_FORK - No resource fork will be stored in the docbase, even
                                     if resource fork file path has been specified
                        USE_RESOURCE_FORK_IF_AVAILABLE - Resource fork will be set to the docbase if supplied
                                               by the caller of the operation
                        REQUIRE_RESOURCE_FORK - Resource fork is required. An error will be generated if
                                      resource fork is not made available.
                        GENERATE_RESOURCE_FORK - A resource fork will be generated if it is not explicitly
                                       available.

    Parameters:
      `option` - - possible values: IGNORE_RESOURCE_FORK, USE_RESOURCE_FORK_IF_AVAILABLE, REQUIRE_RESOURCE_FORK, GENERATE_RESOURCE_FORK.
    Since:
      DFC 5.2.5

  - ### getAcsTransferPreferences

    IDfAcsTransferPreferences getAcsTransferPreferences()
    Returns the `IDfAcsTransferPreferences` object to be used.
    Returns:
      `IDfAcsTransferPreferences` object to be used
    Since:
      5.4

  - ### setAcsTransferPreferences

    void setAcsTransferPreferences(IDfAcsTransferPreferences acsTransferPreferences)
    Sets the `IDfAcsTransferPreferences` object to be used.
    Parameters:
      `acsTransferPreferences` - `IDfAcsTransferPreferences` object to be used
    Since:
      5.4