Placeable (Java Application API for IBM Streams)
Date: 2020-08-07

com.ibm.streamsx.topology.context

## Interface Placeable<T extends Placeable<T>>

- All Superinterfaces:
    TopologyElement
  All Known Subinterfaces:
    SPLStream, TSink, TStream<T>

      public interface Placeable<T extends Placeable<T>>
      extends TopologyElement

  Placement directives for a topology element when executing in a distributed runtime.
  Placement directives only apply when the topology is submitted to a `DISTRIBUTED`, `STREAMING_ANALYTICS_SERVICE` or `DISTRIBUTED_TESTER` context.
  For all other context types directives are ignored.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `T` | `addResourceTags(java.lang.String... tags)` Add required resource tags for this topology element for distributed submission.
    `T` | `colocate(Placeable<?>... elements)` Colocate this element with other topology elements so that at runtime they all execute within the same processing element (PE or operating system process).
    `default java.lang.String` | `getInvocationName()` Return the invocation name of this element.
    `java.util.Set<java.lang.String>` | `getResourceTags()` Get the set of resource tags this element requires.
    `T` | `invocationName(java.lang.String name)` Set the invocation name of this placeable.
    `boolean` | `isPlaceable()` Can this element have placement directives applied to it.
    `com.ibm.streamsx.topology.builder.BOperatorInvocation` | `operator()`

    - ### Methods inherited from interface com.ibm.streamsx.topology.TopologyElement

      `builder, topology`

- - ### Method Detail

    - #### isPlaceable

          boolean isPlaceable()

      Can this element have placement directives applied to it.
      Returns:
        `true` if placement directives can be assigned, `false` if it can not.

    - #### colocate

          T colocate(Placeable<?>... elements)

      Colocate this element with other topology elements so that at runtime they all execute within the same processing element (PE or operating system process). `elements` may contain any `Placeable` within the same topology, there is no requirement that the element is connected (by a stream) directly or indirectly to this element.

      When a set of colocated elements are completely within a single parallel region then the colocation constraint is limited to that channel. So if elements `A` and `B` are colocated then it is guaranteed that `A[0],B[0]` from channel 0 are in a single PE and `A[1],B[1]`from channel 1 are in a single PE, but typically a different PE to `A[0],B[0]`.
      When a a set of colocated elements are not completely within a single parallel region then the colocation constraint applies to the whole topology. So if `A,B` are in a parallel region but `C` is outside then all the replicas of `A,B` are colocated with `C` and each other.

      Colocation is also referred to as fusing, when topology elements are connected by streams then the communication between them is in-process using direct method calls (instead of a network transport such as TCP).

      Parameters:
        `elements` - Elements to colocate with this container.
      Returns:
        this
      Throws:
        `IllegalStateExeception` - Any element including `this` returns `false` for `isPlaceable()`.

    - #### addResourceTags

          T addResourceTags(java.lang.String... tags)

      Add required resource tags for this topology element for distributed submission. This topology element and any it has been `colocated` with will execute on a resource (host) that has all the tags returned by `getResourceTags()`.
      Parameters:
        `tags` - Tags to be required at runtime.
      Returns:
        this

    - #### getResourceTags

          java.util.Set<java.lang.String> getResourceTags()

      Get the set of resource tags this element requires. If this topology element has been `colocated` with other topology elements then the returned set is the union of all `resource tags added` to each colocated element.
      Returns:
        Read-only set of host tags this element requires.

    - #### getInvocationName

          default java.lang.String getInvocationName()

      Return the invocation name of this element. This name is unique within the context of its topology. By default an element has a unique generated invocation name
      Returns:
        Current invocation name if `isPlaceable()` is `true` otherwise `null`.
      Since:
        1.7
      See Also:
        `invocationName(String)`

    - #### invocationName

          T invocationName(java.lang.String name)

      Set the invocation name of this placeable. Allows an invocation name to be assigned to this placeable. The name is visible in the Streams console for a running job and is associated with the logic for this placeable.

      Names must be unique within a topology, if this name is already in use then the '`name_N'` will be used where `N` is a number that makes the name unique within the topology.

      For example the invocation for sending alerts as SMS (text) messages could be named as SMSAlerts:

           TStream<Alert> alerts = ...

           alerts.forEach(Alert::sendAsTextMsg).name("SMSAlerts");

      Note that `name` will eventually resolve into an identifier for an operator name and/or a stream name. Identifiers are limited to ASCII characters, thus `name` will be modified at code generation time if it cannot be represented as an identifier.

      Parameters:
        `name` - Name to assigned.
      Returns:
        This.
      Throws:
        `java.lang.IllegalStateException` - `isPlaceable()` returns `false`.
      Since:
        1.7
      See Also:
        `getInvocationName()`

    - #### operator

          com.ibm.streamsx.topology.builder.BOperatorInvocation operator()