Beacon (openkit-java 2.0.3 API)

java.lang.Object
- com.dynatrace.openkit.protocol.Beacon

```
public class Beacon
extends java.lang.Object
```
The Beacon class holds all the beacon data and the beacon protocol implementation.

Constructor Summary

Constructors
Constructor and Description

Beacon(BeaconInitializer initializer, BeaconConfiguration configuration)
Creates a new beacon instance

Constructors
Constructor and Description
`Beacon(BeaconInitializer initializer, BeaconConfiguration configuration)` Creates a new beacon instance

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addAction(BaseActionImpl action)` Add `BaseActionImpl` to Beacon.
`void`	`addWebRequest(int parentActionID, WebRequestTracerBaseImpl webRequestTracer)` Add web request to Beacon.
`void`	`clearData()` Clears all previously collected data for this Beacon.
`int`	`createID()` Create a unique identifier.
`int`	`createSequenceNumber()` Create a unique sequence number.
`java.lang.String`	`createTag(int parentActionID, int tracerSeqNo)` Create a web request tag.
`void`	`disableCapture()` Disables capturing for this session
`void`	`enableCapture()` Enables capturing for this beacon.
`protected byte[]`	`encodeBeaconChunk(java.lang.String chunkToEncode)` Encodes the given chunk to an `CHARSET` byte array.
`void`	`endSession()` Add `SessionImpl` to Beacon when session is ended.
`long`	`getCurrentTimestamp()` Get the current timestamp in milliseconds by delegating to TimingProvider
`long`	`getDeviceID()` Get a visitor ID for the current data collection level in case of level 2 (USER_BEHAVIOR) the value from the configuration is used in case of level 1 (PERFORMANCE) or 0 (OFF) a random number in the positive Long range is used
`int`	`getSessionNumber()` Get a session ID for the current data collection level
`int`	`getSessionSequenceNumber()` Returns sequence number of the session.
`long`	`getSessionStartTime()` Returns the time when the session was started (in milliseconds).
`void`	`identifyUser(java.lang.String userTag)` Add user identification to Beacon.
`void`	`initializeServerConfiguration(ServerConfiguration serverConfiguration)` Initializes the beacon with the given `ServerConfiguration`.
`boolean`	`isActionReportingAllowedByPrivacySettings()` Get a boolean, indicating if action reporting is enabled by the privacy configuration
`boolean`	`isDataCapturingEnabled()` Indicates whether data capturing for this beacon is currently enabled or not.
`boolean`	`isEmpty()` Tests if the Beacon is empty.
`boolean`	`isServerConfigurationSet()` Indicates whether a server configuration is set on this beacon's configuration or not.
`void`	`reportCrash(java.lang.String errorName, java.lang.String reason, java.lang.String stacktrace)` Add crash to Beacon.
`void`	`reportError(int parentActionID, java.lang.String errorName, int errorCode, java.lang.String reason)` Add error to Beacon.
`void`	`reportEvent(int parentActionID, java.lang.String eventName)` Add event (aka.
`void`	`reportValue(int parentActionID, java.lang.String valueName, double value)` Add key-value-pair to Beacon.
`void`	`reportValue(int parentActionID, java.lang.String valueName, int value)` Add key-value-pair to Beacon.
`void`	`reportValue(int parentActionID, java.lang.String valueName, java.lang.String value)` Add key-value-pair to Beacon.
`StatusResponse`	`send(HTTPClientProvider provider, AdditionalQueryParameters additionalParameters)` Send current state of Beacon.
`void`	`setServerConfigurationUpdateCallback(ServerConfigurationUpdateCallback callback)` Sets the callback when a server configuration is updated.
`void`	`startSession()` Add start session event to Beacon.
`void`	`updateServerConfiguration(ServerConfiguration serverConfiguration)` Updates this beacon with the given `ServerConfiguration`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Beacon
```
public Beacon(BeaconInitializer initializer,
              BeaconConfiguration configuration)
```
    Creates a new beacon instance
    
    Parameters:
    
    initializer - provider of relevant parameters to initialize / create the beacon
    
    configuration - OpenKit related configuration.
- Method Detail
  - createID
```
public int createID()
```
    Create a unique identifier.
    The identifier returned is only unique per Beacon. Calling this method on two different Beacon instances, might give the same result.
    
    Returns:
    
    A unique identifier.
  - getCurrentTimestamp
```
public long getCurrentTimestamp()
```
    Get the current timestamp in milliseconds by delegating to TimingProvider
    
    Returns:
    
    Current timestamp in milliseconds.
  - createSequenceNumber
```
public int createSequenceNumber()
```
    Create a unique sequence number.
    The sequence number returned is only unique per Beacon. Calling this method on two different Beacon instances, might give the same result.
    
    Returns:
    
    A unique sequence number.
  - getSessionStartTime
```
public long getSessionStartTime()
```
    Returns the time when the session was started (in milliseconds).
  - createTag
```
public java.lang.String createTag(int parentActionID,
                                  int tracerSeqNo)
```
    Create a web request tag.
    Web request tags can be attached as HTTP header for web request tracing. If PrivacyConfiguration.isWebRequestTracingAllowed() yields false an empty tag is returned.
    
    Parameters:
    
    parentActionID - The ID of the Action for which to create a web request tag or 0 if no parent action exists.
    
    tracerSeqNo - Sequence number of the WebRequestTracer.
    
    Returns:
    
    A web request tracer tag.
  - addAction
```
public void addAction(BaseActionImpl action)
```
    Add BaseActionImpl to Beacon.
    The serialized data is added to BeaconCache.
    
    Parameters:
    
    action - The action to add.
  - startSession
```
public void startSession()
```
    Add start session event to Beacon.
    The serialized data is added to BeaconCache.
  - endSession
```
public void endSession()
```
    Add SessionImpl to Beacon when session is ended.
    The serialized data is added to BeaconCache.
  - reportValue
```
public void reportValue(int parentActionID,
                        java.lang.String valueName,
                        int value)
```
    Add key-value-pair to Beacon.
    The serialized data is added to BeaconCache.
    
    Parameters:
    
    parentActionID - The ID of the Action on which this value was reported.
    
    valueName - Value's name.
    
    value - Actual value to report.
  - reportValue
```
public void reportValue(int parentActionID,
                        java.lang.String valueName,
                        double value)
```
    Add key-value-pair to Beacon.
    The serialized data is added to BeaconCache.
    
    Parameters:
    
    parentActionID - The ID of the Action on which this value was reported.
    
    valueName - Value's name.
    
    value - Actual value to report.
  - reportValue
```
public void reportValue(int parentActionID,
                        java.lang.String valueName,
                        java.lang.String value)
```
    Add key-value-pair to Beacon.
    The serialized data is added to BeaconCache.
    
    Parameters:
    
    parentActionID - The ID of the Action on which this value was reported.
    
    valueName - Value's name.
    
    value - Actual value to report.
  - reportEvent
```
public void reportEvent(int parentActionID,
                        java.lang.String eventName)
```
    Add event (aka. named event) to Beacon.
    The serialized data is added to BeaconCache.
    
    Parameters:
    
    parentActionID - The ID of the Action on which this event was reported.
    
    eventName - Event's name.
  - reportError
```
public void reportError(int parentActionID,
                        java.lang.String errorName,
                        int errorCode,
                        java.lang.String reason)
```
    Add error to Beacon.
    The serialized data is added to BeaconCache.
    
    Parameters:
    
    parentActionID - The ID of the Action on which this error was reported.
    
    errorName - Error's name.
    
    errorCode - Some error code.
    
    reason - Reason for that error.
  - reportCrash
```
public void reportCrash(java.lang.String errorName,
                        java.lang.String reason,
                        java.lang.String stacktrace)
```
    Add crash to Beacon.
    The serialized data is added to BeaconCache.
    
    Parameters:
    
    errorName - Error's name.
    
    reason - Reason for that error.
    
    stacktrace - Crash stacktrace.
  - addWebRequest
```
public void addWebRequest(int parentActionID,
                          WebRequestTracerBaseImpl webRequestTracer)
```
    Add web request to Beacon.
    The serialized data is added to BeaconCache.
    
    Parameters:
    
    parentActionID - The id of the parent Action on which this web request was reported.
    
    webRequestTracer - Web request tracer to serialize.
  - identifyUser
```
public void identifyUser(java.lang.String userTag)
```
    Add user identification to Beacon.
    The serialized data is added to BeaconCache.
    
    Parameters:
    
    userTag - User tag containing data to serialize.
  - send
```
public StatusResponse send(HTTPClientProvider provider,
                           AdditionalQueryParameters additionalParameters)
```
    Send current state of Beacon.
    This method tries to send all so far collected and serialized data.
    
    Parameters:
    
    provider - Provider for getting an HTTPClient required to send the data.
    
    additionalParameters - additional parameters that will be send with the beacon request (can be null).
    
    Returns:
    
    Returns the last status response retrieved from the server side, or null if an error occurred.
  - encodeBeaconChunk
```
protected byte[] encodeBeaconChunk(java.lang.String chunkToEncode)
                            throws java.io.UnsupportedEncodingException
```
    Encodes the given chunk to an CHARSET byte array.
    This method should only be used by tests.
    
    Parameters:
    
    chunkToEncode - the beacon chunk to encode
    
    Returns:
    
    the encoded beacon chunk
    
    Throws:
    
    java.io.UnsupportedEncodingException
  - clearData
```
public void clearData()
```
    Clears all previously collected data for this Beacon.
    This only affects the so far serialized data, which gets removed from the cache.
  - getDeviceID
```
public long getDeviceID()
```
    Get a visitor ID for the current data collection level in case of level 2 (USER_BEHAVIOR) the value from the configuration is used in case of level 1 (PERFORMANCE) or 0 (OFF) a random number in the positive Long range is used
    
    Returns:
    
    The device identifier, which is truncated to 250 characters if level 2 (USER_BEHAVIOR) is used.
  - getSessionNumber
```
public int getSessionNumber()
```
    Get a session ID for the current data collection level
    If session number reporting is allowed (see also PrivacyConfiguration.isSessionNumberReportingAllowed(), then the real session number is returned, otherwise 1 is returned.
    
    Returns:
    
    Pre calculated session number or 1 if session number reporting is not allowed.
  - getSessionSequenceNumber
```
public int getSessionSequenceNumber()
```
    Returns sequence number of the session.
    The session sequence number is a consecutive number which is increased when a session is split due to exceeding the maximum number of allowed events. The split session will then have the same session number but an increased session sequence number.
  - isEmpty
```
public boolean isEmpty()
```
    Tests if the Beacon is empty.
    A beacon is considered to be empty, if it does not contain any action or event data.
    
    Returns:
    
    true if the beacon is empty, false otherwise.
  - initializeServerConfiguration
```
public void initializeServerConfiguration(ServerConfiguration serverConfiguration)
```
    Initializes the beacon with the given ServerConfiguration.
    
    Parameters:
    
    serverConfiguration - the server configuration which will be used for initialization.
  - updateServerConfiguration
```
public void updateServerConfiguration(ServerConfiguration serverConfiguration)
```
    Updates this beacon with the given ServerConfiguration
    
    Parameters:
    
    serverConfiguration - the server configuration which will be used to update this beacon.
  - isServerConfigurationSet
```
public boolean isServerConfigurationSet()
```
    Indicates whether a server configuration is set on this beacon's configuration or not.
  - setServerConfigurationUpdateCallback
```
public void setServerConfigurationUpdateCallback(ServerConfigurationUpdateCallback callback)
```
    Sets the callback when a server configuration is updated.
    
    Parameters:
    
    callback - the callback to be notified when the server configuration is updated.
  - isDataCapturingEnabled
```
public boolean isDataCapturingEnabled()
```
    Indicates whether data capturing for this beacon is currently enabled or not.
  - enableCapture
```
public void enableCapture()
```
    Enables capturing for this beacon.
    This will implicitly cause isServerConfigurationSet() to return true.
  - disableCapture
```
public void disableCapture()
```
    Disables capturing for this session
    This will implicitly cause isServerConfigurationSet() to return true.
  - isActionReportingAllowedByPrivacySettings
```
public boolean isActionReportingAllowedByPrivacySettings()
```
    Get a boolean, indicating if action reporting is enabled by the privacy configuration
    
    Returns:
    
    true if action reporting is enabled by privacy configuration, false otherwise.

Class Beacon

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Beacon

Method Detail

createID

getCurrentTimestamp

createSequenceNumber

getSessionStartTime

createTag

addAction

startSession

endSession

reportValue

reportValue

reportValue

reportEvent

reportError

reportCrash

addWebRequest

identifyUser

send

encodeBeaconChunk

clearData

getDeviceID

getSessionNumber

getSessionSequenceNumber

isEmpty

initializeServerConfiguration

updateServerConfiguration

isServerConfigurationSet

setServerConfigurationUpdateCallback

isDataCapturingEnabled

enableCapture

disableCapture

isActionReportingAllowedByPrivacySettings