<commit_before>iDigi Push Monitor API
======================

This project contains clients for the iDigi monitor service.  The iDigi monitor
service allows clients to receive asynchronous notification of various events
in iDigi.  More information about the iDigi monitor service may be found on the
[iDigi Website][iDigi]. Log in to your account and check out the iDigi Web
Services programming guide documentation. This source has been contributed by
[Digi International][Digi].

[iDigi][http://www.idigi.com]
[Digi][http://www.digi.com]

Requirements
------------

* [Java SDK][Java]
* [Gradle Build Tool][Gradle]
* [iDigi Account][iDigi]
* An iDigi device - this includes any of Digi's gateway products or another
  iDigi connector like [ConnectPort for PC][CP4PC].

[Java][http://www.java.com]
[Gradle][http://www.gradle.org]
[CP4PC][http://www.github.com/digidotcom/cp4pc]

Usage
-----

Command Line (from project directory):

    $ gradle jar
    
    $ java -jar netty/build/libs/netty.jar <host> <username> <password> <monitorId>

NOTE: This assumes that a monitor has been created using the iDigi Monitor API
(see below).

Example
-------

This example shows how to integrate the iDigi monitor api into an application.

First, create a monitor using the Monitor web service.

    $ cat > request.xml
    <Monitor>
      <monTopic>DeviceCore</monTopic>
      <monTransportType>tcp</monTransportType>
      <monFormatType>json</monFormatType>
      <monBatchSize>1</monBatchSize>
      <monCompression>gzip</monCompression>
      <monBatchDuration>0</monBatchDuration>
    </Monitor>
    $ curl -XPOST -d @request.xml https://user:pass@developer.idigi.com/ws/Monitor
    <?xml version="1.0" encoding="ISO-8859-1"?>
    <result>
       <location>Monitor/1234</location>
    </result>

Next, use the iDigi Monitor client to process messages received from that monitor.

    int monitorId = 1234;
    MonitorClientFactory factory = ...; // see implementations
    PublishMessageListener listener = new PublishMessageListener {
      @Override
      public void messageReceived(Message message) {
        Scanner scanner = new Scanner(message.getPayload());
        while(scanner.hasNextLine()) {
          System.out.println(scanner.nextLine());
        }
      }
    }
    factory.buildClient(monitorId, listener).start();


Implementations
---------------

### Netty

The Netty implementation of the iDigi Push Monitor API provides two
`MonitorClientFactory` implementations:

* `NettyMonitorClientFactory`
* `SecureNettyMonitorClientFactory`

#### NettyMonitorClientFactory

`NettyMonitorClientFactory` sends data (including authentication) over the wire
without encryption. Therefore, this implementation should not be used for
production environments. Production environments should use the
`SecureNettyMonitorClientFactory`.

    NettyMonitorClientFactory factory =
        new NettyMonitorClientFactory('developer.idigi.com', 'user', 'pass');

#### SecureNettyMonitorClientFactory

`SecureNettyMonitorClientFactory` sends and receives data over an SSL TCP
socket.

    SecureNettyMonitorClientFactory factory =
        new SecureNettyMonitorClientFactory('developer.idigi.com', 'user', 'pass');

The constructor above uses a permissive SSL context, so any valid certificate
is accepted from the server.  This is still vulnerable to man-in-the-middle
attacks.  For added security, a program may specify it's own SSL context for
validating certificates.

    SSLContext context = ...; // some custom SSLContext implementation
    SecureNettyMonitorClientFactory factory =
        new SecureNettyMonitorClientFactory('developer.idigi.com', 'user', 'pass', sslContext);


License
-------

This software is open-source software.  Copyright Digi International, 2012.

This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this file,
You can obtain one at http://mozilla.org/MPL/2.0/.
<commit_msg>update license, clean up opening section<commit_after>iDigi Push Monitor API
======================

This project contains clients for the iDigi monitor service. The iDigi monitor
service allows clients to receive asynchronous notification of various events
in iDigi. More information about the iDigi monitor service may be found on the
[iDigi Website][iDigi]. Log in to your account and check out the iDigi Web
Services Programming Guide.

This source has been contributed by [Digi International][Digi].

[iDigi][http://www.idigi.com]
[Digi][http://www.digi.com]

Requirements
------------

* [Java SDK][Java]
* [Gradle Build Tool][Gradle]
* [iDigi Account][iDigi]
* An iDigi device - this includes any of Digi's gateway products or another
  iDigi connector like [ConnectPort for PC][CP4PC].

[Java][http://www.java.com]
[Gradle][http://www.gradle.org]
[CP4PC][http://www.github.com/digidotcom/cp4pc]

Usage
-----

Command Line (from project directory):

    $ gradle jar
    
    $ java -jar netty/build/libs/netty.jar <host> <username> <password> <monitorId>

NOTE: This assumes that a monitor has been created using the iDigi Monitor API
(see below).

Example
-------

This example shows how to integrate the iDigi monitor api into an application.

First, create a monitor using the Monitor web service.

    $ cat > request.xml
    <Monitor>
      <monTopic>DeviceCore</monTopic>
      <monTransportType>tcp</monTransportType>
      <monFormatType>json</monFormatType>
      <monBatchSize>1</monBatchSize>
      <monCompression>gzip</monCompression>
      <monBatchDuration>0</monBatchDuration>
    </Monitor>
    $ curl -XPOST -d @request.xml https://user:pass@developer.idigi.com/ws/Monitor
    <?xml version="1.0" encoding="ISO-8859-1"?>
    <result>
       <location>Monitor/1234</location>
    </result>

Next, use the iDigi Monitor client to process messages received from that monitor.

    int monitorId = 1234;
    MonitorClientFactory factory = ...; // see implementations
    PublishMessageListener listener = new PublishMessageListener {
      @Override
      public void messageReceived(Message message) {
        Scanner scanner = new Scanner(message.getPayload());
        while(scanner.hasNextLine()) {
          System.out.println(scanner.nextLine());
        }
      }
    }
    factory.buildClient(monitorId, listener).start();


Implementations
---------------

### Netty

The Netty implementation of the iDigi Push Monitor API provides two
`MonitorClientFactory` implementations:

* `NettyMonitorClientFactory`
* `SecureNettyMonitorClientFactory`

#### NettyMonitorClientFactory

`NettyMonitorClientFactory` sends data (including authentication) over the wire
without encryption. Therefore, this implementation should not be used for
production environments. Production environments should use the
`SecureNettyMonitorClientFactory`.

    NettyMonitorClientFactory factory =
        new NettyMonitorClientFactory('developer.idigi.com', 'user', 'pass');

#### SecureNettyMonitorClientFactory

`SecureNettyMonitorClientFactory` sends and receives data over an SSL TCP
socket.

    SecureNettyMonitorClientFactory factory =
        new SecureNettyMonitorClientFactory('developer.idigi.com', 'user', 'pass');

The constructor above uses a permissive SSL context, so any valid certificate
is accepted from the server.  This is still vulnerable to man-in-the-middle
attacks.  For added security, a program may specify it's own SSL context for
validating certificates.

    SSLContext context = ...; // some custom SSLContext implementation
    SecureNettyMonitorClientFactory factory =
        new SecureNettyMonitorClientFactory('developer.idigi.com', 'user', 'pass', sslContext);


License
-------

This software is open-source software. Copyright Digi International, 2012.

This Source Code is subject to the terms of the Apache License v. 2.0. If a
copy of the Apache License v2.0 was not distributed with this file, you can
obtain one at http://www.apache.org/licenses.

{'fraction_non_alphanumeric': 0.1037120642086782, 'fraction_numerical': 0.007022824178580386, 'mean_word_length': 3.990613266583229, 'pattern_counts': {'":': 0, '<': 49, '<?xml version=': 2, '>': 51, 'https://': 2, 'lorem ipsum': 0, 'www.': 11, 'xml': 6}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '37557', 'n_tokens_mistral': 2256, 'n_tokens_neox': 2159, 'n_words': 744}