Package com.mouseviator.fsuipc.datarequest.primitives

# Class StringRequest

java.lang.Object
com.mouseviator.fsuipc.datarequest.DataRequest
com.mouseviator.fsuipc.datarequest.primitives.StringRequest

All Implemented Interfaces:
  `IDataRequest<java.lang.String>`

    public class StringRequest
    extends DataRequest
    implements IDataRequest<java.lang.String>

This class implements string data request for use with `FSUIPC` class. Well, FSUIPC will read/write string values as series of bytes, usually terminated as classic C string, by 0 byte. But with Strings we always have this problem with encoding... so to keep the scalability, this data request allows you to set encoding that will be used to convert the internal byte data buffer holding the string to the actual Java string. You can set this encoding using various constructors or by the `setCharset(java.nio.charset.Charset)` method. The charset for encoding/decoding the string will be initialized to the system default, which, mostly, will be UTF-8.

Author:
  Mouseviator

- ## Nested Class Summary

  Nested Classes
  Modifier and Type | Class | Description
  --- | --- | ---
  `static class` | `StringRequest.ValueRetrieveMethod` | This enumeration defines values retrieve method that will be used by `getValue()` method.

  ## Nested classes/interfaces inherited from interface com.mouseviator.fsuipc.datarequest.IDataRequest

  `IDataRequest.RequestType`

- ## Field Summary

  ### Fields inherited from class com.mouseviator.fsuipc.datarequest.DataRequest

  `BUFFER_LENGTH_BYTE, BUFFER_LENGTH_DOUBLE, BUFFER_LENGTH_FLOAT, BUFFER_LENGTH_INT, BUFFER_LENGTH_LONG, BUFFER_LENGTH_SHORT, dataBuffer, MAX_OFFSET_VALUE, MIN_OFFSET_VALUE, offset, type`

- ## Constructor Summary

  Constructors
  Constructor | Description
  --- | ---
  `StringRequest​(int offset, int size)` | Creates a new string data request associated with given offset and the byte data buffer initialized to given size.
  `StringRequest​(int offset, int max_size, java.lang.String value)` | Creates a new string data request associated with given offset and initialized to given string value.
  `StringRequest​(int offset, int max_size, java.lang.String value, java.nio.charset.Charset charset)` | Creates a new string data request associated with given offset and initialized to given string value.If the byte data buffer, that will be result of converting given string value to byte array, is longer than max_size, it will be trimmed to the (max_size - 1) - the last byte will be set to 0.
  `StringRequest​(int offset, java.lang.String value)` | Creates a new string data request associated with given offset and initialized to given string value.
  `StringRequest​(int offset, java.lang.String value, java.nio.charset.Charset charset)` | Creates a new string data request associated with given offset and initialized to given string value.The conversion of the string to byte data buffer will happen using the provided charset.

- ## Method Summary

  Modifier and Type | Method | Description
  --- | --- | ---
  `void` | `allocate​(int size)` | This function will allocate the internat byte data buffer to specified size, creating new buffer, thus, throwing away any data that this data request held before.
  `java.nio.charset.Charset` | `getCharset()` | Return the charset that the `getValue()` and `setValue(java.lang.String)` functions will use to convert to/from string/byte data buffer.
  `java.lang.String` | `getValue()` | Returns the value stored within this data request byte data buffer.
  `java.lang.String` | `getValue​(StringRequest.ValueRetrieveMethod valueRetrieveMethod)` | This function will return underlying byte data buffer as String.
  `StringRequest.ValueRetrieveMethod` | `getValueRetrieveMethod()` | Return the value retrieve method used by this String data request.
  `void` | `setCharset​(java.nio.charset.Charset charset)` | Sets the charset that the `getValue()` and `setValue(java.lang.String)` functions will use to convert to/from string/byte data buffer.
  `void` | `setValue​(java.lang.String value)` | Sets the value to be stored in the byte data buffer of this data request.
  `void` | `setValue​(java.lang.String value, int max_size)` | This function will set value of this StringRequest to given string, but the resulting length of the byte array of the converted string will be max_size.
  `void` | `setValueRetrieveMethod​(StringRequest.ValueRetrieveMethod valueRetrieveMethod)` | Sets the value retrieve method for this String data request.

  ### Methods inherited from class com.mouseviator.fsuipc.datarequest.DataRequest

  `convertStringToByteArray, copyByteArray, getDataBuffer, getDouble, getFloat, getInt, getLong, getOffset, getShort, getSize, getType, getZeroTerminatedString, putDouble, putDouble, putFloat, putFloat, putInt, putInt, putLong, putLong, putShort, putShort, setOffset, setType`

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

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface com.mouseviator.fsuipc.datarequest.IDataRequest

  `getDataBuffer, getOffset, getSize, getType, setOffset, setType`

- ## Constructor Details

  - ### StringRequest

    public StringRequest​(int offset, int size) throws java.security.InvalidParameterException
    Creates a new string data request associated with given offset and the byte data buffer initialized to given size. Note that this is only useful for READ type request. If you use the `setValue(java.lang.String)` method later on this object, the byte array created by this constructor will be discarded.
    Parameters:
      `offset` - An offset to associate this data request with.
      `size` - The size of the byte data buffer to hold the string characters.
    Throws:
      `java.security.InvalidParameterException`

  - ### StringRequest

    public StringRequest​(int offset, java.lang.String value) throws java.security.InvalidParameterException
    Creates a new string data request associated with given offset and initialized to given string value. The conversion of the string to byte data buffer will happen using the system default charset. The data request type will be set to WRITE.
    Parameters:
      `offset` - An offset to associate this data request with.
      `value` - A string to set for this data request value.
    Throws:
      `java.security.InvalidParameterException`

  - ### StringRequest

    public StringRequest​(int offset, int max_size, java.lang.String value) throws java.security.InvalidParameterException
    Creates a new string data request associated with given offset and initialized to given string value. If the byte data buffer, that will be result of converting given string value to byte array, is longer than max_size, it will be trimmed to the (max_size - 1) - the last byte will be set to 0. The conversion of the string to byte data buffer will happen using the system default charset. The data request type will be set to WRITE.
    Parameters:
      `offset` - An offset to associate this data request with.
      `max_size` - Maximum size of the resulting byte data buffer.
      `value` - A string to set for this data request value.
    Throws:
      `java.security.InvalidParameterException`

  - ### StringRequest

    public StringRequest​(int offset, java.lang.String value, java.nio.charset.Charset charset) throws java.security.InvalidParameterException
    Creates a new string data request associated with given offset and initialized to given string value.The conversion of the string to byte data buffer will happen using the provided charset. The data request type will be set to WRITE.
    Parameters:
      `offset` - An offset to associate this data request with.
      `value` - A string to set for this data request value.
      `charset` - A charset to use for string conversion.
    Throws:
      `java.security.InvalidParameterException`

  - ### StringRequest

    public StringRequest​(int offset, int max_size, java.lang.String value, java.nio.charset.Charset charset) throws java.security.InvalidParameterException
    Creates a new string data request associated with given offset and initialized to given string value.If the byte data buffer, that will be result of converting given string value to byte array, is longer than max_size, it will be trimmed to the (max_size - 1) - the last byte will be set to 0. The conversion of the string to byte data buffer will happen using the provided charset. The data request type will be set to WRITE.
    Parameters:
      `offset` - An offset to associate this data request with.
      `max_size` - Maximum size of the resulting byte data buffer.
      `value` - A string to set for this data request value.
      `charset` - A charset to use for string conversion.
    Throws:
      `java.security.InvalidParameterException`

- ## Method Details

  - ### allocate

    public void allocate​(int size)
    This function will allocate the internat byte data buffer to specified size, creating new buffer, thus, throwing away any data that this data request held before.
    Parameters:
      `size` - The required size of the byte data buffer.

  - ### getValue

    public java.lang.String getValue()
    Description copied from interface: `IDataRequest`
    Returns the value stored within this data request byte data buffer.
    Specified by:
      `getValue` in interface `IDataRequest<java.lang.String>`
    Returns:
      The value stored within this data request.

  - ### getValue

    public java.lang.String getValue​(StringRequest.ValueRetrieveMethod valueRetrieveMethod)
    This function will return underlying byte data buffer as String. You have to specify how the value will be retrieved by `valueRetrieveMethod` parameter.
    Parameters:
      `valueRetrieveMethod` - The method to retrieve the value.
    Returns:
      String representation of the underlying byte data buffer.

  - ### setValue

    public void setValue​(java.lang.String value)
    Description copied from interface: `IDataRequest`
    Sets the value to be stored in the byte data buffer of this data request.
    Specified by:
      `setValue` in interface `IDataRequest<java.lang.String>`
    Parameters:
      `value` - The value to store.

  - ### setValue

    public void setValue​(java.lang.String value, int max_size)
    This function will set value of this StringRequest to given string, but the resulting length of the byte array of the converted string will be max_size.
    Parameters:
      `value` - A string value to set.
      `max_size` - The maximum length of the byte buffer of the converted string.

  - ### setCharset

    public void setCharset​(java.nio.charset.Charset charset)
    Sets the charset that the `getValue()` and `setValue(java.lang.String)` functions will use to convert to/from string/byte data buffer.
    Parameters:
      `charset` - A charset to use for string conversion.

  - ### getCharset

    public java.nio.charset.Charset getCharset()
    Return the charset that the `getValue()` and `setValue(java.lang.String)` functions will use to convert to/from string/byte data buffer.
    Returns:
      The charset.

  - ### getValueRetrieveMethod

    public StringRequest.ValueRetrieveMethod getValueRetrieveMethod()
    Return the value retrieve method used by this String data request.
    Returns:
      Value retrieve method.

  - ### setValueRetrieveMethod

    public void setValueRetrieveMethod​(StringRequest.ValueRetrieveMethod valueRetrieveMethod)
    Sets the value retrieve method for this String data request.
    Parameters:
      `valueRetrieveMethod` - Value retrieve method.