com.avaya.ccs.api

## Interface ResourceI

-     public interface ResourceI

  The `ResourceI` object represents a controllable endpoint that can be used to originate or receive interactions.

  An endpoint would generally refer to a physical telephone set or a softphone application. Invoking the `SessionI.openResources(com.avaya.ccs.api.ResourceListenerI)` method will open the stream of notification events for all resources within a `SessionI` to the application and provides access to the `ResourceI` objects.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `callSupervisor()` Request that a call be placed to the user's supervisor.
    `boolean` | `canCallSupervisor()`
    `boolean` | `canOriginate()`
    `java.lang.String` | `getAddress()` The address associated with this resource.
    `java.lang.String` | `getAddressName()` This is the user name (or user information) portion of the resource's address URI (see `getAddress()`).
    `java.util.List<ContactType>` | `getContactTypes()`
    `ContactType` | `getDefaultContactType()` The default contact type for this `ResourceI`.
    `java.lang.String` | `getId()` A unique identifier for the `ResourceI` object.
    `SessionI` | `getSession()`
    `ResourceState` | `getState()` This property provides the current `ResourceState` of the `ResourceI` object.
    `StateReason` | `getStateReason()` The `StateReason` that this `ResourceI` has transitioned to the current `ResourceState`.
    `java.lang.String` | `getStateReasonMessage()` A text string containing a description of why this `ResourceI` is in the current `ResourceState`.
    `boolean` | `hasContactType(ContactType contactType)` Determines if a particular `ContactType` can be handled by this `ResourceI`.
    `void` | `originateVoiceCall(java.lang.String destinationAddress, ContactType contactType)` Requests origination of an outgoing interaction from this device (for example, initiates a voice call).

- - ### Method Detail

    - #### canCallSupervisor

          boolean canCallSupervisor()
                             throws ObjectInvalidException

      Returns:
        `true` if the `callSupervisor()` method can be invoked at this time, `false` if it cannot
      Throws:
        `ObjectInvalidException` - if the `ResourceI` object has been deleted

    - #### canOriginate

          boolean canOriginate()
                        throws ObjectInvalidException

      Returns:
        `true` if the `originateVoiceCall(java.lang.String, com.avaya.ccs.api.enums.ContactType)` method can be invoked at this time, `false` if it cannot
      Throws:
        `ObjectInvalidException` - if the `ResourceI` object has been deleted

    - #### getAddress

          java.lang.String getAddress()
                               throws ObjectInvalidException

      The address associated with this resource. The address is typically represented by a URI (e.g. "sip:123456@domain.com"). To obtain the user name section of the address (e.g. "123456"), use `getAddressName()`.
      Returns:
        the address of the `ResourceI` object
      Throws:
        `ObjectInvalidException` - if the `ResourceI` object has been deleted

    - #### getAddressName

          java.lang.String getAddressName()
                                   throws ObjectInvalidException

      This is the user name (or user information) portion of the resource's address URI (see `getAddress()`). For example if the address is sip:8111674@domain.com, then the address name would be 8111674.
      Returns:
        the user name portion of the address URI
      Throws:
        `ObjectInvalidException` - if the `ResourceI` object has been deleted

    - #### getContactTypes

          java.util.List<ContactType> getContactTypes()
                                               throws ObjectInvalidException

      Returns:
        a list of `ContactType` objects that this `ResourceI` is capable of handling
      Throws:
        `ObjectInvalidException` - if the `ResourceI` object has been deleted

    - #### getDefaultContactType

          ContactType getDefaultContactType()
                                     throws ObjectInvalidException

      The default contact type for this `ResourceI`.

      This property allows the client application to determine what is the default `ContactType` for the device represented by this `ResourceI`. This property is used when no `ContactType` argument is specified in the `originateVoiceCall(java.lang.String, com.avaya.ccs.api.enums.ContactType)` method.

      Returns:
        the default `ContactType` for this `ResourceI`
      Throws:
        `ObjectInvalidException` - if the `ResourceI` object has been deleted

    - #### getId

          java.lang.String getId()

      A unique identifier for the `ResourceI` object.

      Identifier values are only guaranteed to be unique among objects of the same type. Client applications should not rely on the value of the ID property for anything other than uniquely identifying an instance of a particular object type, as the actual value of the ID property may be changed in future releases. The id property is the only property that can be accessed after the object is deleted.

      Returns:
        id of the `ResourceI` object

    - #### getSession

          SessionI getSession()
                       throws ObjectInvalidException

      Returns:
        the `SessionI` object that this `ResourceI` object is associated with
      Throws:
        `ObjectInvalidException` - if the `ResourceI` object has been deleted

    - #### getState

          ResourceState getState()

      This property provides the current `ResourceState` of the `ResourceI` object.

      This property is available for access after the application has received a `NotificationType.DELETE` notification for this `ResourceI` object and will return `ResourceState.Invalid`.

      A resource can be in `ResourceState.OutOfService` for a number of reasons. For instance, it can be out of service if the device associated with it is currently not registered or if the underlying service provider has been taken out of service. The `getStateReason()` and/or `getStateReasonMessage()` properties can be examined to get more detail.

      Returns:
        the `ResourceState` that the resource is currently in

    - #### getStateReason

          StateReason getStateReason()

      The `StateReason` that this `ResourceI` has transitioned to the current `ResourceState`.

      This property is available for access after the application has received a `NotificationType.DELETE` notification for this `ResourceI` object.

      The `StateReason` values that are most applicable to resource state changes are;

      State Reasons
      Reason | Description
      --- | ---
      `StateReason.AcquisitionFailure` | The acquisition of the device this resource represents failed.
      `StateReason.CTILinkDown` | The computer telephony integration (CTI) link has failed. This indicates that control of the endpoint is not currently possible. The endpoint itself may be used during this time to handle voice calls.
      `StateReason.CTILinkUp` | The computer telephony integration (CTI) link has recovered. This indicates that the system can not control the endpoint. Existing calls may still require the use of the endpoint for control.
      `StateReason.DestinationBusy` | There are existing contacts active on the endpoint at the time of resource acquisition
      `StateReason.DeviceNotRegistered` | The endpoint is not registered or logged in to the telephony switch
      `StateReason.DeviceNotConfigured` | The endpoint is not configured on the telephony switch
      `StateReason.DeviceNotSupported` | The type of endpoint is not supported or the endpoint has a configuration that is not supported
      `StateReason.LicenseNotGranted` | A required license was not granted
      `StateReason.ProviderOutOfService` | The service provider for the endpoint is currently out of service
      `StateReason.ResourceDisabled` | The resource is disabled.

      Returns:
        the `StateReason` of the latest state change

    - #### getStateReasonMessage

          java.lang.String getStateReasonMessage()

      A text string containing a description of why this `ResourceI` is in the current `ResourceState`. The value is null if there is no reason message available.

      This property is available for access after the application has received a `NotificationType.DELETE` notification for this `ResourceI` object.

      Returns:
        a string containing a description of the reason this `ResourceI` is in the current `ResourceState`. The value is `null` if there is no reason message.

    - #### callSupervisor

          void callSupervisor()
                       throws ObjectInvalidException

      Request that a call be placed to the user's supervisor.

      If a failure occurs a `NotificationType.ERROR` notification will be received by the application. This notification is sent to the `ResourceListenerI` implementation that is supplied by the application as an argument to the `SessionI.openResources(com.avaya.ccs.api.ResourceListenerI)` method.

      Possible errors for this method are listed below. Most errors can be prevented by querying the `canCallSupervisor()` method to determine when it is possible to invoke this method. If the meaning of the error code in the context of this method differs significantly from the generic description given for that error code, then a context-specific meaning is given.

      Possible Errors
      Error Codes | Context Specific Meaning / Notes
      --- | ---
      `ErrorCode.DestinationBusy`
      `ErrorCode.DestinationOutOfService`
      `ErrorCode.DestinationStateInvalid`
      `ErrorCode.OperationNotSupported`
      `ErrorCode.OutOfService`

      Throws:
        `ObjectInvalidException` - if the `ResourceI` object has been deleted

    - #### hasContactType

          boolean hasContactType(ContactType contactType)
                          throws ObjectInvalidException,
                                 InvalidArgumentException

      Determines if a particular `ContactType` can be handled by this `ResourceI`.
      Parameters:
        `contactType` - the `ContactType` to check
      Returns:
        `true` if the `ContactType` is found on the resource, `false` if not
      Throws:
        `ObjectInvalidException` - if the `ResourceI` has been deleted
        `InvalidArgumentException` - if the supplied `ContactType` argument is null

    - #### originateVoiceCall

          void originateVoiceCall(java.lang.String destinationAddress,
                                  ContactType contactType)
                           throws ObjectInvalidException,
                                  InvalidArgumentException

      Requests origination of an outgoing interaction from this device (for example, initiates a voice call).

      If successful, a `NotificationType.NEW` notification for an `InteractionI` object that represents the outgoing Contact to the specified destination will be received. This notification is sent to the `InteractionListenerI` implementation that is supplied by the application as an argument to the `SessionI.openInteractions(com.avaya.ccs.api.InteractionListenerI)` method.

      If a failure occurs a `NotificationType.ERROR` notification will be received. This notification is sent to the `ResourceListenerI` implementation that is supplied by the application as an argument to the `SessionI.openResources(com.avaya.ccs.api.ResourceListenerI)` method.

      Possible errors for this method are listed below. Most errors can be prevented by querying `canOriginate()` method to determine when it is possible to call this method. If the meaning of the error code in the context of this method differs significantly from the generic description given for that error code, then a context-specific meaning is given.

      Possible Errors
      Error Codes | Context Specific Meaning / Notes
      --- | ---
      `ErrorCode.CommServerError` | A malformed destination address was provided.
      `ErrorCode.DestinationBusy`
      `ErrorCode.DestinationInvalid`
      `ErrorCode.DestinationOutOfService`
      `ErrorCode.DestinationStateInvalid`
      `ErrorCode.DestinationUnreachable`
      `ErrorCode.InvalidContactType` | The contact type argument specified a `ContactType` that is not supported by the resource.
      `ErrorCode.OutOfService`

      Note that even if the operation fails, an `InteractionI` object may actually have been created depending on the service provider and the `ContactType`. An example of this is a voice call to a busy number. This may be represented by the creation of an `InteractionI` with a `RemoteParticipantI` in `RemoteParticipantState.Failed` and receipt a `NotificationType.ERROR` notification containing `ErrorCode.DestinationBusy`. On a telephony switch, this failed call may be necessary to allow the busy tone to be heard in the receiver. It also allows the user to manually drop this failed call. Other error codes may share this behavior; for instance `ErrorCode.DestinationUnreachable` or `ErrorCode.DestinationInvalid`.

      Parameters:
        `destinationAddress` - a string representing the destination address to contact (for example,the phone number to dial).
        `contactType` - (optional) the type of contact to originate. if specified, this must match one of the available contact types for this resource as determined from `getContactTypes()`. if `null` is supplied for this argument, then `getDefaultContactType()` will be used.
      Throws:
        `ObjectInvalidException` - if the `ResourceI` has been deleted
        `InvalidArgumentException` - if `null` or an empty string is provided for the `destinationAddress` argument