com.sap.conn.jco

## Interface JCoDestination

- All Known Subinterfaces:
    JCoCustomDestination

      public interface JCoDestination

  JCoDestination identifies a physical destination of a function call. It contains all required properties in order to connect to an SAP system.

  Note: A JCoDestination is only a configuration instance that contains all necessary information for the JCo runtime to create a connection. It does not create or hold any connections by itself. The JCo runtime creates connections and pools them if defined by the destination configuration.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `changePassword(String oldPassword, String newPassword)` Allows changing the password in the back-end for the user associated with the destination.
    `void` | `confirmFunctionUnit(JCoUnitIdentifier unitIdentifier)` Confirms that a bgRFC unit has been executed successfully.
    `void` | `confirmTID(String tid)` Confirms that a transaction (tRFC/qRFC) has been executed successfully.
    `JCoCustomDestination` | `createCustomDestination()` Creates a new instance of custom destination with default values set from the current destination.
    `String` | `createTID()` Creates a new transaction ID that can be used for tRFC/qRFC requests.
    `String` | `getAliasUser()` Returns the alias of the logon user as specified in the destination properties.
    `String` | `getApplicationServerHost()` Returns the host name of the ABAP instance as specified in the destination properties.
    `JCoAttributes` | `getAttributes()` Returns the attributes of the destination.
    `String` | `getClient()` Returns SAP client as specified in the destination properties.
    `String` | `getDestinationID()` Returns internal id of this destination instance.
    `String` | `getDestinationName()` Returns name of destination.
    `long` | `getExpirationCheckPeriod()` Returns the time in ms, after which a timeout checker will close the expired connections.
    `long` | `getExpirationTime()` Returns the time in ms, after which a free connection, that is held internally for the destination, is being regarded as expired and will be closed during the next run of the expiration timeout checker.
    `String` | `getExternalIDData()` Returns the external identification user logon data as specified in the destination properties.
    `String` | `getExternalIDType()` Returns the type of the external identification user logon data as specified in the destination properties.
    `JCoFunctionUnitState` | `getFunctionUnitState(JCoUnitIdentifier unitIdentifier)` Returns the state of the unit with the given ID.
    `String` | `getGatewayHost()` Returns the gateway host as specified in the destination properties.
    `String` | `getGatewayService()` Returns the gateway service as specified in the destination properties.
    `String` | `getLanguage()` Returns the logon language as specified in the destination properties.
    `String` | `getLogonCheck()` Returns the logon check mode as specified in the destination properties.
    `String` | `getLogonGroup()` Returns the logon group as specified in the destination properties.
    `long` | `getMaxGetClientTime()` Returns the max time in ms for the allocation of a connection to a destination in case that the peak limit is already reached.
    `String` | `getMessageServerHost()` Returns the SAP message server as specified in the destination properties.
    `String` | `getMessageServerService()` Returns the SAP message server port as specified in the destination properties.
    `JCoDestinationMonitor` | `getMonitor()` Returns a monitor instance describing the client connections that have been created by the JCo runtime for this destination instance.
    `int` | `getPeakLimit()` Returns the maximum number of connections, that can be created for the destination simultaneously.
    `int` | `getPoolCapacity()` Returns the maximum number of idle connections, that will be kept open in a pool.
    `Properties` | `getProperties()` Returns the complete property set describing the destination.
    `String` | `getR3Name()` Returns the System ID of the SAP system as specified in the destination properties.
    `JCoRepository` | `getRepository()` Returns a repository instance that contains metadata for this destination.
    `JCoDestinationMonitor` | `getRepositoryDestinationMonitor()` Returns a monitor instance describing the client connections that have been created by the JCo runtime for the repository queries done via this destination instance.
    `String` | `getRepositoryUser()` Returns the user that is used for communication when executing repository queries via this destination if there is no repository destination configured.
    `String` | `getSAPRouterString()` Returns the SAP router string as specified in the destination properties.
    `String` | `getSncLibrary()` Returns the path to SNC library as specified in the destination properties.
    `String` | `getSncMode()` Returns the SNC mode as specified in the destination properties.
    `String` | `getSncMyName()` Returns the own SNC name as specified in the destination properties.
    `String` | `getSncPartnerName()` Returns the SNC partner as specified in the destination properties.
    `String` | `getSncQOP()` Returns the SNC level of security as specified in the destination properties.
    `String` | `getSncSSO()` Returns the SNC SSO mode as specified in the destination properties.
    `String` | `getSystemNumber()` Returns the SAP system number as specified in the destination properties.
    `JCoThroughput` | `getThroughput()` Returns the throughput instance.
    `String` | `getTPHost()` Returns the host of external server program as specified in the destination properties.
    `String` | `getTPName()` Returns the Program ID of external server program as specified in the destination properties.
    `char` | `getType()` Returns the type of the destination.
    `String` | `getUser()` Returns the logon user as specified in the destination properties.
    `boolean` | `isPooledConnectionChecked()` Returns whether a pooled connection will be checked for corruption before being used for the next function module execution.
    `boolean` | `isValid()` Returns true if the corresponding destination configuration was neither changed nor removed, false otherwise.
    `void` | `ping()` Executes a connection test for this destination.
    `void` | `removeThroughput()` Removes the throughput instance from this destination.
    `void` | `setThroughput(JCoThroughput throughput)` Sets the throughput instance for measuring the RFC executions to this destination.

- - ### Method Detail

    - #### getDestinationName

          String getDestinationName()

      Returns name of destination. Destination Name is a user defined non-unique name.
      Returns:
        String as destination name

    - #### getDestinationID

          String getDestinationID()

      Returns internal id of this destination instance.
      Returns:
        String as destination id

    - #### getType

          char getType()

      Returns the type of the destination.
      Possible types are (depending on the runtime environment):
      - `3` - Destination to an ABAP system with unspecified logon method
      - `A` - Destination to an ABAP system with direct application server host logon
      - `B` - Destination to an ABAP system with message server driven load balanced logon
      - `E` - Destination to an external RFC server program
      - `R` - Destination to a registered RFC server program
      - `N` - Destination to an on-premise ABAP system with unspecified logon method within SAP Cloud Platform
      Returns:
        char type of the destination

    - #### getApplicationServerHost

          String getApplicationServerHost()

      Returns the host name of the ABAP instance as specified in the destination properties. Returns null if this property was not set.
      Returns:
        host name of the ABAP instance

    - #### getSAPRouterString

          String getSAPRouterString()

      Returns the SAP router string as specified in the destination properties. Returns null if this property was not set. The format of the router string is as follows:
      `(/H/<host>[/S/<port>][/P/<password>])+`
      Returns:
        SAP router string

    - #### getGatewayHost

          String getGatewayHost()

      Returns the gateway host as specified in the destination properties. Returns null if this property was not set.
      Returns:
        Gateway host

    - #### getGatewayService

          String getGatewayService()

      Returns the gateway service as specified in the destination properties. Returns null if this property was not set.
      Returns:
        Gateway service

    - #### getSystemNumber

          String getSystemNumber()

      Returns the SAP system number as specified in the destination properties. Returns null if this property was not set.
      Returns:
        SAP system number

    - #### getLogonGroup

          String getLogonGroup()

      Returns the logon group as specified in the destination properties. Returns null if this property was not set.
      Returns:
        logon group

    - #### getMessageServerHost

          String getMessageServerHost()

      Returns the SAP message server as specified in the destination properties. Returns null if this property was not set.
      Returns:
        SAP message server

    - #### getMessageServerService

          String getMessageServerService()

      Returns the SAP message server port as specified in the destination properties. Returns null if this property was not set.
      Returns:
        SAP message server port

    - #### getR3Name

          String getR3Name()

      Returns the System ID of the SAP system as specified in the destination properties. Returns null if this property was not set.
      Returns:
        System ID of the SAP system

    - #### getTPHost

          String getTPHost()

      Returns the host of external server program as specified in the destination properties. Returns null if this property was not set.
      Returns:
        Host of external server program

    - #### getTPName

          String getTPName()

      Returns the Program ID of external server program as specified in the destination properties. Returns null if this property was not set.
      Returns:
        Program ID of external server program

    - #### getSncLibrary

          String getSncLibrary()

      Returns the path to SNC library as specified in the destination properties. Returns null if this property was not set.
      Returns:
        path to SNC library

    - #### getSncMode

          String getSncMode()

      Returns the SNC mode as specified in the destination properties. Returns null if this property was not set.
      Returns:
        SNC mode

    - #### getSncMyName

          String getSncMyName()

      Returns the own SNC name as specified in the destination properties. Returns null if this property was not set.
      Returns:
        own SNC name

    - #### getSncPartnerName

          String getSncPartnerName()

      Returns the SNC partner as specified in the destination properties. Returns null if this property was not set.
      Returns:
        SNC partner name

    - #### getSncQOP

          String getSncQOP()

      Returns the SNC level of security as specified in the destination properties. Returns null if this property was not set.
      Returns:
        SNC level of security

    - #### getSncSSO

          String getSncSSO()

      Returns the SNC SSO mode as specified in the destination properties. Returns null if this property was not set.
      Returns:
        SNC SSO mode
      Since:
        JCo 3.0.9

    - #### getAliasUser

          String getAliasUser()

      Returns the alias of the logon user as specified in the destination properties. Returns null if this property was not set.
      Returns:
        alias of the logon user

    - #### getClient

          String getClient()

      Returns SAP client as specified in the destination properties. Returns null if this property was not set.
      Returns:
        SAP client

    - #### getLanguage

          String getLanguage()

      Returns the logon language as specified in the destination properties. Returns null if this property was not set.
      Returns:
        logon language

    - #### getUser

          String getUser()

      Returns the logon user as specified in the destination properties. Returns null if this property was not set.
      Returns:
        logon user

    - #### getLogonCheck

          String getLogonCheck()

      Returns the logon check mode as specified in the destination properties. Returns null if this property was not set.
      Returns:
        logon check mode

    - #### getExternalIDData

          String getExternalIDData()

      Returns the external identification user logon data as specified in the destination properties. Returns null if this property was not set.
      Returns:
        external ID data
      Since:
        JCo 3.0.9

    - #### getExternalIDType

          String getExternalIDType()

      Returns the type of the external identification user logon data as specified in the destination properties. Returns null if this property was not set.
      Returns:
        external ID type
      Since:
        JCo 3.0.9

    - #### getPeakLimit

          int getPeakLimit()

      Returns the maximum number of connections, that can be created for the destination simultaneously. This value is always greater than or equal to pool capacity.
      Returns:
        maximum number of active connections

    - #### getPoolCapacity

          int getPoolCapacity()

      Returns the maximum number of idle connections, that will be kept open in a pool.
      A value of `0` means that the connections will be closed immedeatly after being released, which has the effect that there is no connection pooling.
      Returns:
        maximum number of pooled connections

    - #### getExpirationTime

          long getExpirationTime()

      Returns the time in ms, after which a free connection, that is held internally for the destination, is being regarded as expired and will be closed during the next run of the expiration timeout checker.
      A value of `0` means that the connections will be closed immediately after release.
      Returns:
        expiration time

    - #### getExpirationCheckPeriod

          long getExpirationCheckPeriod()

      Returns the time in ms, after which a timeout checker will close the expired connections.
      Returns:
        the length of the check interval in ms

    - #### getMaxGetClientTime

          long getMaxGetClientTime()

      Returns the max time in ms for the allocation of a connection to a destination in case that the peak limit is already reached.
      Returns:
        max wait time in ms

    - #### isPooledConnectionChecked

          boolean isPooledConnectionChecked()

      Returns whether a pooled connection will be checked for corruption before being used for the next function module execution. Thus, it is possible to recognize corrupted connections, and avoid exceptions passed to applications if connectivity is working in principle. Drawback: There's a performance impact for working connections.
      Returns:
        returns true if check is performed false if not.
      Since:
        JCo 3.1.0

    - #### getProperties

          Properties getProperties()

      Returns the complete property set describing the destination. The values of security relevant properties like passwords, logon tickets or certificates are truncated or replaced by dummy values.
      Returns:
        Properties object describing the destination.

    - #### getAttributes

          JCoAttributes getAttributes()
                                      throws JCoException

      Returns the attributes of the destination.
      Returns:
        destination attributes
      Throws:
        `JCoException` - if an exception occurs during the initialization of the destination

    - #### getRepository

          JCoRepository getRepository()
                                      throws JCoException

      Returns a repository instance that contains metadata for this destination. The repository will use either this destination instance for remote queries or the destination specified by repository destination property
      Returns:
        JCoRepository instance
      Throws:
        `JCoException` - if an exception occurs during the initialization of the associated repository destination

    - #### getRepositoryUser

          String getRepositoryUser()

      Returns the user that is used for communication when executing repository queries via this destination if there is no repository destination configured.
      Returns:
        the user used for repository queries

    - #### createCustomDestination

          JCoCustomDestination createCustomDestination()

      Creates a new instance of custom destination with default values set from the current destination. It is possible to modify the user logon data on the customizable destination.
      Returns:
        JCoCustomDestination a new instance of JCoCustomDestination
      See Also:
        `JCoCustomDestination.getUserLogonData()`, `JCoCustomDestination.getSNCConfiguration()`

    - #### confirmTID

          void confirmTID(String tid)
                          throws JCoException

      Confirms that a transaction (tRFC/qRFC) has been executed successfully.
      Parameters:
        `tid` - the ID of the transaction to confirm
      Throws:
        `JCoException` - thrown if something went wrong during the confirmation

    - #### createTID

          String createTID()
                           throws JCoException

      Creates a new transaction ID that can be used for tRFC/qRFC requests.
      Returns:
        the newly created transaction ID as a string
      Throws:
        `JCoException` - thrown if something went wrong during the creation

    - #### confirmFunctionUnit

          void confirmFunctionUnit(JCoUnitIdentifier unitIdentifier)
                                   throws JCoException

      Confirms that a bgRFC unit has been executed successfully.
      Parameters:
        `unitIdentifier` - the identifier of the function unit
      Throws:
        `JCoException` - thrown if something went wrong during the confirmation

    - #### getFunctionUnitState

          JCoFunctionUnitState getFunctionUnitState(JCoUnitIdentifier unitIdentifier)
                                                    throws JCoException

      Returns the state of the unit with the given ID. This API allows the client side to ask the server for the current state of a function unit. Usually this API will be used after failure on the client side, if the state information for particular units is missing.
      Parameters:
        `unitIdentifier` - the identifier of the function unit
      Returns:
        the state of the function unit
      Throws:
        `JCoException` - thrown if something went wrong during the confirmation

    - #### setThroughput

          void setThroughput(JCoThroughput throughput)

      Sets the throughput instance for measuring the RFC executions to this destination. A previously defined throughput instance will be overwritten.
      Parameters:
        `throughput` - the throughput instance for storing the performance data

    - #### getThroughput

          JCoThroughput getThroughput()

      Returns the throughput instance.
      Returns:
        the throughput instance

    - #### removeThroughput

          void removeThroughput()

      Removes the throughput instance from this destination. The measuring will be deactivated.

    - #### ping

          void ping()
                    throws JCoException

      Executes a connection test for this destination.
      Throws:
        `JCoException` - thrown if something went wrong during the ping

    - #### isValid

          boolean isValid()

      Returns true if the corresponding destination configuration was neither changed nor removed, false otherwise.
      Returns:
        true if destination configuration was neither changed nor removed
      Since:
        JCo 3.0.7

    - #### changePassword

          void changePassword(String oldPassword,
                            String newPassword)
                              throws JCoException

      Allows changing the password in the back-end for the user associated with the destination. Please note, that this won't change the configuration in the registered DestinationDataProvider. This needs to be adjusted separately!
      Parameters:
        `oldPassword` - the old password of the user
        `newPassword` - the new password chosen for the user
      Throws:
        `JCoException` - thrown if something went wrong during the password change
      Since:
        JCo 3.0.6

    - #### getMonitor

          JCoDestinationMonitor getMonitor()
                                           throws JCoRuntimeException

      Returns a monitor instance describing the client connections that have been created by the JCo runtime for this destination instance.
      Returns:
        a monitor instance
      Throws:
        `JCoRuntimeException` - in case of destination instance is already removed or was not initialized properly

    - #### getRepositoryDestinationMonitor

          JCoDestinationMonitor getRepositoryDestinationMonitor()

      Returns a monitor instance describing the client connections that have been created by the JCo runtime for the repository queries done via this destination instance. This method may return null, if this destination has not been used for any metadata query.
      Returns:
        a monitor instance or null

Copyright © 2019 SAP. All Rights Reserved.