### *** This class provides Binary Compatibility only, not Source Compatibility ***

Package com.sas.services.discovery

# Class HostAttribute

java.lang.Object
com.sas.services.AbstractServiceAttribute
com.sas.services.discovery.HostAttribute

All Implemented Interfaces:
  `ServiceAttributeInterface`, `Serializable`

@SASScope("ALL") @BinaryCompatibilityOnly public final class HostAttribute extends AbstractServiceAttribute
A foundation service discovery attribute which may be used to locate a service which has been deployed on a particular host by using the host's name and/or IP address.

When a service is deployed, a `HostAttribute` will be added to its service discovery configuration for each `InetAddress` associated with its host. This will enable one to find a service that is deployed on a particular host.

## Examples

Examples are provided to find a foundation service deployed on:

- this host
- a host using the host's name
- a host using its IP address

## Example 1: Find a service that was deployed on this host

This example shows how to define a service template that can be used to discover an Authentication Service that was deployed on this host.

To find a service that was deployed on this host, define a service template that specifies one or more interfaces that the desired service must satisfy and a `HostAttribute` initialized to the desired host by specifying either the host's name and/or its IP address.

     import java.net.InetAddress;

     import com.sas.services.discovery.DiscoveryService;
     import com.sas.services.discovery.HostAttribute;
     import com.sas.services.discovery.ServiceTemplate;
     import com.sas.services.security.AuthenticationServiceInterface;

     ...

     // define a service template that can be used to
     // lookup an Authentication Service
     Class[] desiredServiceInterface = new Class[] {
        AuthenticationServiceInterface.class};

     // get this host's InetAddress
     // note: a host may have multiple addresses
     InetAddress inetAddress = getInetAddress();

     ServiceAttributeInterface serviceAttributes = new ServiceAttributeInterface[] {
        new HostAttribute(inetAddress)};

     // create a service lookup template specifying the required
     // service interface(s) and a service attribute for a
     // service that was deployed on this host
     ServiceTemplate serviceTemplate = new ServiceTemplate(
        desiredServiceInterface,
        serviceAttributes);

     // discover a service satisfying the service template
     AuthenticationServiceInterface authenticationService = (AuthenticationServiceInterface)
        DiscoveryService.defaultInstance().findService(serviceTemplate);

     ...

     // Utility method used to determine the host's InetAddress:

     import java.net.InetAddress;
     import java.net.NetworkInterface;
     import java.util.Enumeration;

     import com.sas.services.deployment.RMIConfiguration;

     ...

     // get this host's InetAddress discarding the "localhost" address
     InetAddress getInetAddress () {

        InetAddress theInetAddress = null;

        try {
           final Enumeration netInterfaces = NetworkInterface.getNetworkInterfaces();
           NetworkInterface networkInterface = null;
           InetAddress inetAddress = null;
           Enumeration inetAddresses = null;
           while (netInterfaces.hasMoreElements()) {
                networkInterface= (NetworkInterface) netInterfaces.nextElement();
                inetAddresses = networkInterface.getInetAddresses();
                while (inetAddresses.hasMoreElements()) {
                   inetAddress = (InetAddress) inetAddresses.nextElement();
                  if (!RMIConfiguration.LOCALHOST.equals(inetAddress.getHostName())) {
                     theInetAddress = inetAddress;
                     break;
                  }
               }
            }
         }
         catch (ClassCastException e) {
            // handle exception
         }

         return theInetAddress;

     }

## Example 2: Find a service that was deployed on a host using its name

This example shows how to define a service template that can be used to discover a foundation Authentication service that was deployed on a host named "xxx.acme.com".

To find a service that was deployed on this host, define a service template that specifies one or more interfaces that the desired service must satisfy and a `HostAttribute` initialized using the host's name.

     import com.sas.services.discovery.DiscoveryService;
     import com.sas.services.discovery.HostAttribute;
     import com.sas.services.discovery.ServiceTemplate;
     import com.sas.services.security.AuthenticationServiceInterface;

     ...

     // define a service template that can be used to
     // lookup an Authentication Service
     Class[] desiredServiceInterface = new Class[] {
        AuthenticationServiceInterface.class};

     // the name of the desired host on which a service was deployed
     String hostName = "xxx.acme.com";

     // find a service on for a given host name
     ServiceAttributeInterface serviceAttributes = new ServiceAttributeInterface[] {
        new HostAttribute(
           hostName,
           null)};//don't care about the host's address

     // create a service lookup template specifying the required
     // service interface(s) and a service attribute for a
     // service that was deployed on the specified host
     ServiceTemplate serviceTemplate = new ServiceTemplate(
        desiredServiceInterface,
        serviceAttributes);

     // discover a service satisfying the service template
     AuthenticationServiceInterface authenticationService = (AuthenticationServiceInterface)
        DiscoveryService.defaultInstance().findService(serviceTemplate);

## Example 3: Find a service that was deployed on a host using its address

This example shows how to define a service template that can be used to discover a foundation Authentication service that was deployed on a host whose IP address is "99.99.99.99".

To find a service that was deployed on this host, define a service template that specifies one or more interfaces that the desired service must satisfy and a `HostAttribute` initialized using the host's address.

     import com.sas.services.discovery.DiscoveryService;
     import com.sas.services.discovery.HostAttribute;
     import com.sas.services.discovery.ServiceTemplate;
     import com.sas.services.security.AuthenticationServiceInterface;

     ...

     // define a service template that can be used to
     // lookup an Authentication Service
     Class[] desiredServiceInterface = new Class[] {
        AuthenticationServiceInterface.class};

     // the IP address of the desired host on which a service was deployed
     String hostAddress = "99.99.99.99";

     // find a service on for a given host name
     ServiceAttributeInterface serviceAttributes = new ServiceAttributeInterface[] {
        new HostAttribute(
           null,//don't care about the host's name
           hostAddress)};

     // create a service lookup template specifying the required
     // service interface(s) and a service attribute for a
     // service that was deployed on the specified host
     ServiceTemplate serviceTemplate = new ServiceTemplate(
        desiredServiceInterface,
        serviceAttributes);

     // discover a service satisfying the service template
     AuthenticationServiceInterface authenticationService = (AuthenticationServiceInterface)
        DiscoveryService.defaultInstance().findService(serviceTemplate);

Since:
  9.2
See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `String`
  `address`
  The host's IP address.
  `String`
  `host`
  The host's name.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `HostAttribute()`
  Constructs a service discovery attribute representing a host with its name and address to `null`.
  `HostAttribute(String hostName)`
  Constructs an attribute which may be used to locate a remotely accessible foundation service which was deployed on a particular host.
  `HostAttribute(String hostName, String hostAddress)`
  Constructs a service discovery attribute representing a host using the specified name and address.
  `HostAttribute(InetAddress inetAddress)`
  Constructs a service discovery attribute representing a host by initializing the host's name and address using values obtained from `InetAddress.getHostName()` and `InetAddress.getHostAddress()`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Map<String,String>`
  `getFieldNameToValueMap()`
  Gets a map of this attribute's fields and their values.

  ### Methods inherited from class com.sas.services.AbstractServiceAttribute

  `equals, hashCode, toString`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### host

    public String host
    The host's name.

  - ### address

    public String address
    The host's IP address.

- ## Constructor Details

  - ### HostAttribute

    public HostAttribute()
    Constructs a service discovery attribute representing a host with its name and address to `null`.

  - ### HostAttribute

    public HostAttribute(InetAddress inetAddress)
    Constructs a service discovery attribute representing a host by initializing the host's name and address using values obtained from `InetAddress.getHostName()` and `InetAddress.getHostAddress()`.

    Since this attribute initializes both the name and address, a client can locate a foundation service deployed on a particular host by matching the host's name and/or address.

    One may also use `HostAttribute(String, String)` to construct an instance using string values for the host's name and address.

    Parameters:
      `inetAddress` - An address representing the host on which a foundation service has been deployed.
    Throws:
      `IllegalArgumentException` - if a `null` parameter is specified.

  - ### HostAttribute

    public HostAttribute(String hostName)
    Constructs an attribute which may be used to locate a remotely accessible foundation service which was deployed on a particular host.
    Parameters:
      `hostName` - Internet host name.

  - ### HostAttribute

    public HostAttribute(String hostName, String hostAddress)
    Constructs a service discovery attribute representing a host using the specified name and address.

    A convenience constructor `HostAttribute(InetAddress)` is also provided if one would prefer to initialize this attribute using a host name and address obtained from an `InetAddress`.

    Parameters:
      `hostName` - Internet host name.
      `hostAddress` - Internet host address.

- ## Method Details

  - ### getFieldNameToValueMap

    public Map<String,String> getFieldNameToValueMap()
    Gets a map of this attribute's fields and their values.
    - host
    - address
    Overrides:
      `getFieldNameToValueMap` in class `AbstractServiceAttribute`
    Returns:
      Map keyed by the `String` names of a field to their values.