PROTON-1799: Remove deprecated bindings and APIs
Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/0c9bb9ff Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/0c9bb9ff Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/0c9bb9ff Branch: refs/heads/master Commit: 0c9bb9ffc6af4cb197f524483df61e9a0bc05272 Parents: c82de9d Author: Justin Ross <[email protected]> Authored: Tue Mar 20 11:32:48 2018 -0700 Committer: Justin Ross <[email protected]> Committed: Tue Mar 20 11:32:48 2018 -0700 ---------------------------------------------------------------------- .travis.yml | 5 +- CMakeLists.txt | 2 +- DEVELOPERS.md | 2 +- INSTALL.md | 20 +- appveyor.yml | 2 +- bin/jenkins-proton-c-build.sh | 2 +- config.bat.in | 12 - config.sh.in | 14 - docs/markdown/index.md | 5 +- .../messenger/addressing-and-routing.md | 210 --- docs/markdown/messenger/index.md | 13 - docs/markdown/messenger/message-disposition.md | 196 --- docs/markdown/messenger/quick-start-linux.md | 73 - .../markdown/messenger/sending-and-receiving.md | 144 -- proton-c/CMakeLists.txt | 10 - proton-c/bindings/CMakeLists.txt | 39 +- proton-c/bindings/javascript/CMakeLists.txt | 279 --- proton-c/bindings/javascript/LICENSE | 203 --- proton-c/bindings/javascript/README | 426 ----- proton-c/bindings/javascript/TODO | 49 - proton-c/bindings/javascript/binding-close.js | 33 - proton-c/bindings/javascript/binding-open.js | 21 - proton-c/bindings/javascript/binding.c | 36 - proton-c/bindings/javascript/data-array.js | 100 -- proton-c/bindings/javascript/data-binary.js | 181 -- proton-c/bindings/javascript/data-described.js | 74 - proton-c/bindings/javascript/data-long.js | 191 --- proton-c/bindings/javascript/data-symbol.js | 59 - .../bindings/javascript/data-typed-number.js | 108 -- proton-c/bindings/javascript/data-uuid.js | 107 -- proton-c/bindings/javascript/data.js | 1582 ------------------ proton-c/bindings/javascript/error.js | 172 -- proton-c/bindings/javascript/message.js | 840 ---------- proton-c/bindings/javascript/messenger.js | 822 --------- proton-c/bindings/javascript/module.js | 481 ------ .../javascript/qpid-proton-messenger/LICENSE | 203 --- .../javascript/qpid-proton-messenger/README.md | 94 -- .../qpid-proton-messenger/lib/.gitignore | 21 - .../qpid-proton-messenger/package.json | 18 - proton-c/bindings/javascript/subscription.js | 81 - proton-c/bindings/node/CMakeLists.txt | 71 - proton-c/bindings/node/binding.gyp.in | 31 - proton-c/bindings/node/javascript.i | 42 - proton-c/bindings/perl/CMakeLists.txt | 74 - proton-c/bindings/perl/LICENSE | 203 --- proton-c/bindings/perl/MANIFEST | 10 - proton-c/bindings/perl/Makefile.PL | 12 - proton-c/bindings/perl/README | 17 - proton-c/bindings/perl/TODO | 2 - proton-c/bindings/perl/lib/qpid/proton.pm | 75 - .../bindings/perl/lib/qpid/proton/Constants.pm | 172 -- proton-c/bindings/perl/lib/qpid/proton/Data.pm | 1276 -------------- .../bindings/perl/lib/qpid/proton/Errors.pm | 26 - .../perl/lib/qpid/proton/ExceptionHandling.pm | 53 - .../bindings/perl/lib/qpid/proton/Mapping.pm | 121 -- .../bindings/perl/lib/qpid/proton/Message.pm | 538 ------ .../bindings/perl/lib/qpid/proton/Messenger.pm | 353 ---- .../bindings/perl/lib/qpid/proton/Tracker.pm | 39 - .../perl/lib/qpid/proton/array_helper.pm | 147 -- proton-c/bindings/perl/lib/qpid/proton/utils.pm | 38 - proton-c/bindings/perl/lib/qpid_proton.pm | 38 - proton-c/bindings/perl/perl.i | 216 --- proton-c/bindings/perl/tests/array_helper.t | 232 --- proton-c/bindings/perl/tests/data.t | 536 ------ proton-c/bindings/perl/tests/hash_helper.t | 74 - proton-c/bindings/perl/tests/message.t | 254 --- proton-c/bindings/perl/tests/messenger.t | 129 -- proton-c/bindings/perl/tests/utils.pm | 60 - proton-c/bindings/php/.gitignore | 1 - proton-c/bindings/php/CMakeLists.txt | 117 -- proton-c/bindings/php/compat.swg | 50 - proton-c/bindings/php/cproton.ini | 21 - proton-c/bindings/php/get_include_dir.php | 55 - proton-c/bindings/php/php.i | 229 --- proton-c/bindings/php/proton.ini.in | 21 - proton-c/bindings/php/proton.php | 1119 ------------- proton-c/bindings/php/tests.php | 64 - proton-c/bindings/python/proton/__init__.py | 615 ------- .../bindings/ruby/lib/messenger/messenger.rb | 703 -------- .../bindings/ruby/lib/messenger/subscription.rb | 36 - proton-c/bindings/ruby/lib/messenger/tracker.rb | 37 - .../ruby/lib/messenger/tracker_status.rb | 68 - proton-c/bindings/ruby/lib/qpid_proton.rb | 7 - .../ruby/tests/old_examples/old_example_test.rb | 8 - .../bindings/ruby/tests/old_examples/recv.rb | 23 - .../bindings/ruby/tests/old_examples/send.rb | 21 - tests/javascript/codec.js | 569 ------- tests/javascript/message.js | 359 ---- tests/javascript/msgr-recv.js | 265 --- tests/javascript/msgr-send-common.js | 245 --- tests/javascript/msgr-send.html | 123 -- tests/javascript/msgr-send.js | 100 -- tests/javascript/soak.js | 93 - tests/javascript/unittest.js | 45 - tests/python/proton_tests/__init__.py | 1 - tests/python/proton_tests/common.py | 13 - tests/python/proton_tests/messenger.py | 1089 ------------ tests/python/proton_tests/soak.py | 34 - tests/python/proton_tests/ssl.py | 122 -- tests/smoke/recv.php | 27 - tests/smoke/recv.pl | 23 - tests/smoke/recv.py | 23 - tests/smoke/recv.rb | 24 - tests/smoke/send.php | 27 - tests/smoke/send.pl | 17 - tests/smoke/send.py | 24 - tests/smoke/send.rb | 24 - tests/tools/apps/python/msgr-recv.py | 206 --- tests/tools/apps/python/msgr-send.py | 205 --- tools/cmake/Modules/FindEmscripten.cmake | 40 - tools/cmake/Modules/FindNodePackages.cmake | 72 - tools/cmake/Modules/ProtonFindPerl.cmake | 81 - 112 files changed, 17 insertions(+), 18798 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/0c9bb9ff/.travis.yml ---------------------------------------------------------------------- diff --git a/.travis.yml b/.travis.yml index 568d100..fe09339 100644 --- a/.travis.yml +++ b/.travis.yml @@ -37,7 +37,7 @@ matrix: env: - PKG_CONFIG_PATH='/usr/local/opt/openssl/lib/pkgconfig' - PATH="/usr/local/opt/python/libexec/bin:/usr/local/bin:$PATH" - - QPID_PROTON_CMAKE_ARGS='-DPROACTOR=libuv -DSASL_IMPL=none -DCMAKE_OSX_DEPLOYMENT_TARGET=10.11 -DBUILD_PERL=OFF -DBUILD_RUBY=OFF' + - QPID_PROTON_CMAKE_ARGS='-DPROACTOR=libuv -DSASL_IMPL=none -DCMAKE_OSX_DEPLOYMENT_TARGET=10.11 -DBUILD_RUBY=OFF' before_install: - brew update - brew upgrade cmake python openssl @@ -48,7 +48,7 @@ matrix: env: - PKG_CONFIG_PATH='/usr/local/opt/openssl/lib/pkgconfig' - PATH="/usr/local/opt/python/libexec/bin:/usr/local/bin:$PATH" - - QPID_PROTON_CMAKE_ARGS='-DPROACTOR=libuv -DSASL_IMPL=none -DCMAKE_OSX_DEPLOYMENT_TARGET=10.13 -DBUILD_PERL=OFF -DBUILD_RUBY=OFF' + - QPID_PROTON_CMAKE_ARGS='-DPROACTOR=libuv -DSASL_IMPL=none -DCMAKE_OSX_DEPLOYMENT_TARGET=10.13 -DBUILD_RUBY=OFF' before_install: - brew update - brew upgrade cmake python openssl @@ -69,7 +69,6 @@ addons: - ruby - ruby-dev - python3-dev - - php5 - golang - lcov http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/0c9bb9ff/CMakeLists.txt ---------------------------------------------------------------------- diff --git a/CMakeLists.txt b/CMakeLists.txt index 48e1d5f..4934451 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -149,7 +149,7 @@ set (BINDINGS_DIR ${LIB_INSTALL_DIR}/proton/bindings) set (SYSINSTALL_BINDINGS OFF CACHE BOOL "If SYSINSTALL_BINDINGS is OFF then proton bindings will be installed underneath ${BINDINGS_DIR} and each user will need to modify their interpreter configuration to load the appropriate binding. If SYSINSTALL_BINDINGS is ON, then each language interpreter will be queried for the appropriate directory and proton bindings will be installed and available system wide with no additional per user configuration.") -set (BINDING_LANGS PERL PHP PYTHON RUBY) +set (BINDING_LANGS PYTHON RUBY) foreach (LANG ${BINDING_LANGS}) set (SYSINSTALL_${LANG} OFF CACHE BOOL "Install ${LANG} bindings into interpreter specified location.") http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/0c9bb9ff/DEVELOPERS.md ---------------------------------------------------------------------- diff --git a/DEVELOPERS.md b/DEVELOPERS.md index 5eaa235..65eee2c 100644 --- a/DEVELOPERS.md +++ b/DEVELOPERS.md @@ -15,7 +15,7 @@ the file config.sh from the CMake build directory. $ source config.sh This file sets the necessary environment variables for all supported -dynamic languages (Python, Perl, Ruby, PHP) and for running the tests. +dynamic languages (Python and Ruby) and for running the tests. Testing ------- http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/0c9bb9ff/INSTALL.md ---------------------------------------------------------------------- diff --git a/INSTALL.md b/INSTALL.md index 2253816..430d648 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -46,8 +46,6 @@ language. $ yum install swig # Required for all bindings $ yum install python-devel # Python $ yum install ruby-devel rubygem-minitest # Ruby - $ yum install php-devel # PHP - $ yum install perl-devel # Perl # Dependencies needed to generate documentation $ yum install epydoc # Python @@ -68,7 +66,7 @@ language binding you can omit the dev package for that language. $ apt-get install libsasl2-2 libsasl2-dev libsasl2-modules # dependencies needed for bindings - $ apt-get install swig python-dev ruby-dev libperl-dev + $ apt-get install swig python-dev ruby-dev # dependencies needed for python docs $ apt-get install python-epydoc @@ -169,7 +167,7 @@ libraries in order to place them in a default search path. When `SYSINSTALL_BINDINGS` is enabled (`ON`), the `CMAKE_INSTALL_PREFIX` does not affect the location for where the -language bindings (Python, Perl, PHP, Ruby) are installed. For those +language bindings (Python and Ruby) are installed. For those elements, the location is determined by the language interpreter itself; that is, each interpreter is queried for the proper location for extensions. @@ -182,23 +180,21 @@ dynamic language bindings into a central, default location: In order to use these bindings, you'll need to configure your interpreter to load the bindings from the appropriate directory. - - Perl - Add ${BINDINGS}/perl to PERL5LIB - - PHP - Set the PHPRC envvar to point to ${BINDINGS}/php/proton.ini - Python - Add ${BINDINGS}/python to PYTHONPATH - Ruby - Add ${BINDINGS}/ruby to RUBYLIB You can configure the build to install a specific binding to the location specified by the system interpreter with the -SYSINSTALL_[LANGUAGE] options, where [LANGUAGE] is one of PERL, -PHP, PYTHON, or RUBY. +SYSINSTALL_[LANGUAGE] options, where [LANGUAGE] is one of PYTHON +or RUBY. - $ cmake .. -DSYSINSTALL_PHP=ON + $ cmake .. -DSYSINSTALL_PYTHON=ON Disabling Language Bindings --------------------------- To disable any given language bindings, you can use the -BUILD_[LANGUAGE] option where [LANGUAGE] is one of PERL, PHP, -PYTHON or RUBY, for example: +BUILD_[LANGUAGE] option where [LANGUAGE] is one of PYTHON +or RUBY, for example: - $ cmake .. -DBUILD_PHP=OFF + $ cmake .. -DBUILD_PYTHON=OFF http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/0c9bb9ff/appveyor.yml ---------------------------------------------------------------------- diff --git a/appveyor.yml b/appveyor.yml index 712609f..80f1585 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -14,7 +14,7 @@ cache: before_build: - mkdir BLD - cd BLD -- cmake -G "%CMAKE_GENERATOR%" -DBUILD_PERL=no %QPID_PROTON_CMAKE_ARGS% .. +- cmake -G "%CMAKE_GENERATOR%" %QPID_PROTON_CMAKE_ARGS% .. - cd .. build: project: BLD/Proton.sln http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/0c9bb9ff/bin/jenkins-proton-c-build.sh ---------------------------------------------------------------------- diff --git a/bin/jenkins-proton-c-build.sh b/bin/jenkins-proton-c-build.sh index 6ed22a9..8b710c1 100755 --- a/bin/jenkins-proton-c-build.sh +++ b/bin/jenkins-proton-c-build.sh @@ -30,7 +30,7 @@ echo Arch: `arch` Uname: `uname -a` lsb_release: `lsb_release -a` User: `whoami` echo ========================= echo Listing installed packages dpkg -l | \ - awk '/^ii (cmake |maven |ruby |python |php |.*jdk |swig[0-9]*)/{print $2, $3}'| \ + awk '/^ii (cmake |maven |ruby |python |.*jdk |swig[0-9]*)/{print $2, $3}'| \ sort echo ========================= http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/0c9bb9ff/config.bat.in ---------------------------------------------------------------------- diff --git a/config.bat.in b/config.bat.in index d40f45d..d8c958e 100644 --- a/config.bat.in +++ b/config.bat.in @@ -40,22 +40,10 @@ set PYTHON_BINDINGS=%PROTON_BINDINGS%\python set COMMON_PYPATH=%PROTON_HOME%\tests\python;%PROTON_HOME%\proton-c\bindings\python set PYTHONPATH=%COMMON_PYPATH%;%PYTHON_BINDINGS% -REM PHP -set PHP_BINDINGS=%PROTON_BINDINGS%\php -if EXIST %PHP_BINDINGS% ( - echo include_path="%PHP_BINDINGS%;%PROTON_HOME%\proton-c\bindings\php" > %PHP_BINDINGS%\php.ini - echo extension="%PHP_BINDINGS%\cproton.so" >> %PHP_BINDINGS%\php.ini - set PHPRC=%PHP_BINDINGS%\php.ini -) - REM Ruby set RUBY_BINDINGS=%PROTON_BINDINGS%\ruby set RUBYLIB=%RUBY_BINDINGS%;%PROTON_HOME%\proton-c\bindings\ruby\lib;%PROTON_HOME%\tests\ruby -REM Perl -set PERL_BINDINGS=%PROTON_BINDINGS%\perl -set PERL5LIB=%PERL5LIB%;%PERL_BINDINGS%;%PROTON_HOME%\proton-c\bindings\perl\lib - REM test applications set PATH=%PATH%;%PROTON_BUILD%\tests\tools\apps\c set PATH=%PATH%;%PROTON_HOME%\tests\tools\apps\python http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/0c9bb9ff/config.sh.in ---------------------------------------------------------------------- diff --git a/config.sh.in b/config.sh.in index d3f50ff..bcb7ede 100755 --- a/config.sh.in +++ b/config.sh.in @@ -34,30 +34,16 @@ PROTON_BUILD=@CMAKE_BINARY_DIR@ PROTON_BINDINGS=$PROTON_BUILD/proton-c/bindings PYTHON_BINDINGS=$PROTON_BINDINGS/python -PHP_BINDINGS=$PROTON_BINDINGS/php -PERL_BINDINGS=$PROTON_BINDINGS/perl # Python COMMON_PYPATH=$PROTON_HOME/tests/python:$PROTON_HOME/proton-c/bindings/python:$PROTON_HOME/tools/py export PYTHONPATH=$COMMON_PYPATH:$PYTHON_BINDINGS -# PHP -if [ -d $PHP_BINDINGS ]; then - cat <<EOF > $PHP_BINDINGS/php.ini -include_path="$PHP_BINDINGS:$PROTON_HOME/proton-c/bindings/php" -extension="$PHP_BINDINGS/cproton.so" -EOF - export PHPRC=$PHP_BINDINGS/php.ini -fi - # Ruby RUBY_BINDINGS=$PROTON_BINDINGS/ruby RUBY_SRC=$PROTON_HOME/proton-c/bindings/ruby export RUBYLIB=$RUBY_BINDINGS:$RUBY_SRC/lib:$RUBY_SRC/tests:$RUBY_SRC/spec -# Perl -export PERL5LIB=$PERL5LIB:$PERL_BINDINGS:$PROTON_HOME/proton-c/bindings/perl/lib - # Go export GOPATH="$PROTON_BUILD/proton-c/bindings/go" # Help Go compiler find libraries and include files. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/0c9bb9ff/docs/markdown/index.md ---------------------------------------------------------------------- diff --git a/docs/markdown/index.md b/docs/markdown/index.md index 0f0a8e3..97ce4f2 100644 --- a/docs/markdown/index.md +++ b/docs/markdown/index.md @@ -1,8 +1,6 @@ Proton is a library for speaking AMQP, including: -- The AMQP [Messenger API](messenger/index.html), a simple but powerful interface to send and receive - messages over AMQP. - The [AMQP Protocol Engine](engine/engine.html), a succinct encapsulation of the full AMQP protocol machinery. @@ -18,8 +16,7 @@ globally federated topologies Proton is multi-lingual: -- Proton-C - a C implementation with language bindings in Python, Php, Perl, -Ruby, and Java (via JNI). +- Proton-C - a C implementation with language bindings in C++, Go, Python, and Ruby - Proton-J - a pure Java implementation Please see http://qpid.apache.org/proton for a more info. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/0c9bb9ff/docs/markdown/messenger/addressing-and-routing.md ---------------------------------------------------------------------- diff --git a/docs/markdown/messenger/addressing-and-routing.md b/docs/markdown/messenger/addressing-and-routing.md deleted file mode 100644 index 9714e1e..0000000 --- a/docs/markdown/messenger/addressing-and-routing.md +++ /dev/null @@ -1,210 +0,0 @@ - -Messenger Addressing and Routing -================================================= - - -Addressing -------------------------- - -An address has the following form: - - [ amqp[s]:// ] [user[:password]@] domain [/[name]] - -Where domain can be one of: - - host | host:port | ip | ip:port | name - -The following are valid examples of addresses: - - * example.org - * example.org:1234 - * amqp://example.org - * amqps://example.org - * example.org/incoming - * amqps://example.org/outgoing - * amqps://fred:[email protected] - * 127.0.0.1:1234 - * amqps://127.0.0.1:1234 - -The "/name" part of the address, that optionally follows -the domain, is not used by the Messenger library. -For example, if a receiver subscribes to - - amqp://~0.0.0.0:5678 - -Then it will receive messages sent to - - amqp://~0.0.0.0:5678 -as well as - amqp://~0.0.0.0:5678/foo - - -Likewise, if the receiver subscribes to - - amqp://~0.0.0.0:5678/foo - -it will receive messages addressed to - - amqp://~0.0.0.0:5678/foo - amqp://~0.0.0.0:5678 - -and - - amqp://~0.0.0.0:5678/bar - - - - -<br/> - -Routing ------------------------------- - -### Pattern Matching, Address Translation, and Message Routing ### - -The Messenger library provides message routing capability -with an address translation table. Each entry in the table -consists of a *pattern* and a *translation*. - -You store a new route entry in the table with the call: - - pn_messenger_route(messenger, pattern, translation); - - -The address of each outgoing message is compared to the -table's patterns until the first matching pattern is found, -or until all patterns have failed to match. - -If no pattern matches, then Messenger will send (or attempt -to send) your message with the address as given. - -If a pattern does match your outgoing message's address, then -Messenger will create a temporary address by transforming -your message's address. Your message will be sent to the -transformed address, but **(note!)** the address on your -outgoing message will not be changed. The receiver will see -the original, not the transformed address. - - -<br/> - -### Two Translation Mechanisms ### - - -Messenger uses two mechanisms to translate addresses. -The first is simple string substitution. - - - pattern: COLOSSUS - translation: amqp://0.0.0.0:6666 - input addr: COLOSSUS - result: amqp://0.0.0.0:6666 - - -The second mechanism is wildcard/variable substitution. -A wildcard in the pattern matches all or part of your -input address. The part of your input address that matched -the wildcard is stored. The matched value is then inserted -into your translated address in place of numbered variables: -$1, $2, and so on, up to a maximum of 64. - -There are two wildcards: * and % . -The rules for matching are: - - * matches anything - % matches anything but a / - other characters match themselves - the whole input addr must be matched - - -Examples of wildcard matching: - - pattern: /%/%/% - translation: $1x$2x$3 - input addr: /foo/bar/baz - result: fooxbarxbaz - - pattern: * - translation: $1 - inout addr: /foo/bar/baz - result: /foo/bar/baz - - pattern: /* - translation: $1 - input addr: /foo/bar/baz - result: foo/bar/baz - - pattern: /*baz - translation: $1 - input addr: /foo/bar/baz - result: foo/bar/ - - pattern: /%baz - translation: $1 - input addr: /foo/bar/baz - result: FAIL - - pattern: /%/baz - translation: $1 - input addr: /foo/bar/baz - result: FAIL - - pattern: /%/%/baz - translation: $1 - input addr: /foo/bar/baz - result: foo - - pattern: /*/baz - translation: $1 - input addr: /foo/bar/baz - result: foo/bar - - -Examples of route translation usage: - - pattern: foo - translation: amqp://foo.com - explanation: Any message sent to "foo" will be routed to "amqp://foo.com" - - - pattern: bar/* - translation: amqp://bar.com/$1 - explanation: Any message sent to bar/<path> will be routed to the corresponding path within the amqp://bar.com domain. - - - pattern: amqp:* - translation: amqps:$1 - explanation: Route all messages over TLS. - - - pattern: amqp://foo.com/* - translation: amqp://user:[email protected]/$1 - explanation: Supply credentials for foo.com. - - - pattern: amqp://* - translation: amqp://user:password@$1 - explanation: Supply credentials for all domains. - - - pattern: amqp://%/* - translation: amqp://user:password@proxy/$1/$2 - explanation: Route all addresses through a single proxy while preserving the - original destination. - - - pattern: * - translation: amqp://user:password@broker/$1 - explanation: Route any address through a single broker. - - - -<br/> - -### First Match Wins ### - -If you create multiple routing rules, each new rule is appended -to your Messenger's list. At send-time, Messenger looks down the -list, and the first rule that matches your outgoing message's -address wins. Thus, when creating your routing rules, you should -create them in order of most specific first, most general last. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/0c9bb9ff/docs/markdown/messenger/index.md ---------------------------------------------------------------------- diff --git a/docs/markdown/messenger/index.md b/docs/markdown/messenger/index.md deleted file mode 100644 index e8ccaa4..0000000 --- a/docs/markdown/messenger/index.md +++ /dev/null @@ -1,13 +0,0 @@ -Proton Messenger Documentation -========================================== - -Proton Messenger is a high-level API that lets you build simple but powerful messaging systems. - -- Use the [Linux Quick Start](quick-start-linux.html) to download, build, and run your first Messenger example in two minutes. - -- Examples and explanations of Messenger's [Sending and Receiving](sending-and-receiving.html) capabilities. - -- Use [Message Disposition](message-disposition.html) functionality to create reliable messaging systems. - -- Messenger's [Addressing and Routing](addressing-and-routing.html) capabilities allow you to separate application code from installation-specific configuration information. - http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/0c9bb9ff/docs/markdown/messenger/message-disposition.md ---------------------------------------------------------------------- diff --git a/docs/markdown/messenger/message-disposition.md b/docs/markdown/messenger/message-disposition.md deleted file mode 100644 index 70d551f..0000000 --- a/docs/markdown/messenger/message-disposition.md +++ /dev/null @@ -1,196 +0,0 @@ -Message Disposition -=============================== - - -Messenger disposition operations allow a receiver to accept or -reject specific messages, or ranges of messages. Senders can -then detect the disposition of their messages. - - -Message States ---------------------------- - -Messages have one of four different states: - `PN_STATUS_UNKNOWN` - `PN_STATUS_PENDING` - `PN_STATUS_ACCEPTED` - `PN_STATUS_REJECTED` - -<br/> - - -Windows and Trackers ----------------------------- - -<br/> - -Messenger does not track the disposition of every message that -it sends or receives. To set (or get) the disposition of a -message, that message must be within your incoming (or outgoing) -window. - -( I will use the incoming direction as the example. The outgoing -direction works similarly. ) - -When you call - - pn_messenger_set_incoming_window(messenger, window_size); - -you have only declared the window size. The window is not yet -created. The window will be created when you issue your first -call to - - pn_messenger_get(messenger, msg); - -And the window will be further populated only by further calls to -pn_messenger_get(). - - - - - - - -### Receiving ### - -To explicitly set or get message dispositions, your messenger -must set a positive size for its incoming window: - - pn_messenger_set_incoming_window(messenger, N); - -You can implicitly accept messages by simply letting enough -new messages arrive. As older messages pass beyond the threshold -of your incoming window size, they will be automatically -accepted. Thus, if you want to automatically accept all -messages as they arrive, you can set your incoming window -size to 0. - -To exercise *explicit* control over particular messages or ranges -of messages, the receiver can use trackers. The call - - pn_messenger_incoming_tracker(messenger); - -will return a tracker for the message most recently returned -by a call to - - pn_messenger_get(messenger, message); -With a message that is being tracked, the messenger can accept -(or reject) that individual message: - - pn_messenger_accept(messenger, tracker, 0); - pn_messenger_reject(messenger, tracker, 0); - -Or it can accept (or reject) the tracked message as well as all older -messages back to the limit of the incoming window: - - pn_messenger_accept(messenger, tracker, PN_CUMULATIVE); - pn_messenger_reject(messenger, tracker, PN_CUMULATIVE); - -Once a message is accepted or rejected, its status can no longer -be changed, even if you have a separate tracker associated with it. - - - -<br/> - -###When to Accept### - -Although you *can* accept messages implicitly by letting them fall -off the edge of your incoming window, you *shouldn't*. Message -disposition is an important form of communication to the sender. -The best practice is to let the sender know your response, by -explicit acceptance or rejection, as soon as you can. Implicitly -accepting messages by allowing them to fall off the edge of the -incoming window could delay your response to the sender for an -unpredictable amount of time. - -A nonzero window size places a limit on -how much state your Messenger needs to track. - -<br/> - -###Accepting by Accident#### - -If you allow a message to "fall off the edge" of your incoming -window before you have explicitly accepted or rejected it, then -it will be accepted automatically. - -But since your incoming window is only filled by calls to - - pn_messenger_get(messenger, msg); - -messages cannot be forced to fall over the edge by simply -receiving more messages. Messages will not be forced over the -edge of the incoming window unless you make too many calls to -`pn_messenger_get()` without explicitly accepting or rejecting -the messages. - -Your application should accept or reject each message as soon -as practical after getting and processing it. - - - - -<br/> -<br/> - - - -### Sending ### - -A sender can learn how an individual message has been received -if it has a positive outgoing window size: - - pn_messenger_set_outgoing_window(messenger, N); - -and if a tracker has been associated with that message in question. -This call: - - pn_messenger_outgoing_tracker(messenger); - -will return a tracker for the message most recently given to: - - pn_messenger_put(messenger, message); - -To later find the status of the individual tracked message, you can call: - - pn_messenger_status(messenger, tracker); - -The returned value will be one of - -* `PN_STATUS_ACCEPTED` -* `PN_STATUS_REJECTED` , or -* `PN_STATUS_PENDING` - If the receiver has not disposed the message yet. - - -If either the sender or the receiver simply declares the message (or range of messages) to -be settled, with one of these calls: - - pn_messenger_settle(messenger, tracker, 0); - pn_messenger_settle(messenger, tracker, PN_CUMULATIVE); - -then the sender will see `PN_STATUS_PENDING` as the status of any -settled messages. - -<br/> - - -### Message Rejection ### -If a message is rejected by the receiver, it does not mean that -the message was malformed. Malformed messages cannot be sent. -Even messages with no content are valid messages. -Rejection by a receiver should be understood as the receiver -saying "I don't want this." or possibly "I don't want this *yet*." -depending on your application. -The sender could decide to try sending the same message again later, -or to send the message to another receiver, or to discard it. - -The AMQP 1.0 specification permits a distinction -between *rejecting* the message, and *releasing* the message, -but the Proton library does not expose the *releasing* -disposition. - - - - - http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/0c9bb9ff/docs/markdown/messenger/quick-start-linux.md ---------------------------------------------------------------------- diff --git a/docs/markdown/messenger/quick-start-linux.md b/docs/markdown/messenger/quick-start-linux.md deleted file mode 100644 index e8ef466..0000000 --- a/docs/markdown/messenger/quick-start-linux.md +++ /dev/null @@ -1,73 +0,0 @@ -Linux Proton Messenger Quick Start -============================================== - - -On a Linux system, these instructions take you from -zero to running your first example code. You will -need root privileges for one of the commands. - - - - -Prerequisite Packages ---------------------------------- - -For a minimum build, you will need packages installed on your -box for : - - subversion - gcc - cmake - libuuid-devel - - - -Quick Start Commands ---------------------------- - - svn co http://svn.apache.org/repos/asf/qpid/proton/trunk proton - cd ./proton - mkdir ./build - cd ./build - cmake .. - make all - # Become root and go to your build dir. - make install - # Stop being root. - # Now let's see if it works. - cd ./proton-c/examples/messenger/c - ./recv & - ./send - # You're done ! ( Kill that recv process. ) - # The output you should see: - - Address: amqp://0.0.0.0 - Subject: (no subject) - Content: "Hello World!" - - - - - -Notes ----------------------------- - -1. If you will be editing and checking in code from this tree, - replace the "svn co" line with this: - - svn co https://svn.apache.org/repos/asf/qpid/proton/trunk - - You must check out through https, or you will not be able to - check in code changes from your tree. - - -2. The recv application in the example defaults to the same port - as the qpid demon. If you happen to have that demon running, - and using the default port, the recv app above will fail. - - -3. If you don't have root privileges, you can still do the - "make install" step by setting a non-standard prefix, thus: - cmake -DCMAKE_INSTALL_PREFIX=/my/path .. - - http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/0c9bb9ff/docs/markdown/messenger/sending-and-receiving.md ---------------------------------------------------------------------- diff --git a/docs/markdown/messenger/sending-and-receiving.md b/docs/markdown/messenger/sending-and-receiving.md deleted file mode 100644 index 555075e..0000000 --- a/docs/markdown/messenger/sending-and-receiving.md +++ /dev/null @@ -1,144 +0,0 @@ -Sending and Receiving Messages -======================================================= - -The Proton Messenger API provides a mixture of synchronous -and asynchronous operations to give you flexibility in -deciding when you application should block waiting for I/O, -and when it should not. - - -When sending messages, you can: - -* send a message immediately, -* enqueue a message to be sent later, -* block until all enqueued messages are sent, -* send enqueued messages until a timeout occurs, or -* send all messages that can be sent without blocking. - -When receiving messages, you can: - -* receive messages that can be received without blocking, -* block until at least one message is received, -* receive no more than a fixed number of messages. - - - -Functions ------------------------------- - -* `pn_messenger_put(messenger)` - - Stage message for later transmission, and possibly - transmit any messages currently staged that are not - blocked. - This function will not block. - - - -* `pn_messenger_send(messenger)` - - If messenger timeout is negative (initial default), - block until all staged messages have been sent. - - If messenger timeout is 0, send all messages that - can be sent without blocking. - - If messenger timeout is positive, send all messages - that can be sent until timeout expires. - - *note: If there are any messages that can be received - when `pn_messenger_send()` is called, they will - be received.* - - - -* `pn_messenger_get(messenger, msg)` - - Dequeue the head of the incoming message queue to - your application. - This call does not block. - - - -* `pn_messenger_recv(messenger)` - - If messenger timeout is negative(initial default), - block until at least one message is received. - - If timeout is 0, receive whatever messages are available, - but do not block. - - If timeout is positive, receive available messages until - timeout expires. - - *note: If there are any unblocked outgoing messages, - they will be sent during this call.* - - - - - -Examples ------------------------------- - -* send a message immediately - - pn_messenger_put(messenger, msg); - pn_messenger_send(messenger); - - - -* enqueue a message to be sent later - - pn_messenger_put(messenger, msg); - - *note: - The message will be sent whenever it is not blocked and - the Messenger code has other I/O work to be done.* - - - -* block until all enqueued messages are sent - - pn_messenger_set_timeout(messenger, -1); - pn_messenger_send(messenger); - - *note: - A negative timeout means 'forever'. That is the initial - default for a messenger.* - - - -* send enqueued messages until a timeout occurs - - pn_messenger_set_timeout(messenger, 100); /* 100 msec */ - pn_messenger_send(messenger); - - - -* send all messages that can be sent without blocking - - pn_messenger_set_timeout(messenger, 0); - pn_messenger_send(messenger); - - - -* receive messages that can be received without blocking - - pn_messenger_set_timeout(messenger, 0); - pn_messenger_recv(messenger, -1); - - -* block until at least one message is received - - pn_messenger_set_timeout(messenger, -1); - pn_messenger_recv(messenger, -1); - - *note: -1 is initial messenger default.* - - - -* receive no more than a fixed number of messages - - pn_messenger_recv(messenger, 10); - http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/0c9bb9ff/proton-c/CMakeLists.txt ---------------------------------------------------------------------- diff --git a/proton-c/CMakeLists.txt b/proton-c/CMakeLists.txt index 381d533..a6c48ec 100644 --- a/proton-c/CMakeLists.txt +++ b/proton-c/CMakeLists.txt @@ -193,14 +193,9 @@ endif (PN_WINAPI) # Try to keep any platform specific overrides together here: -# Until we can decide what to do with PHP support, turn it off by default -# (We can't build with recent versions of PHP) -set (NOBUILD_PHP ON) - # MacOS has a bunch of differences in build tools and process and so we have to turn some things # off if building there: if (APPLE) - set (NOBUILD_PHP ON) set (NOENABLE_WARNING_ERROR ON) set (NOENABLE_UNDEFINED_ERROR ON) endif (APPLE) @@ -814,8 +809,3 @@ if (BUILD_PYTHON) add_dependencies(quick_perf_py reactor-recv _cproton) endif (BUILD_PYTHON) - -if (BUILD_JAVASCRIPT) - add_test (javascript-codec ${env_py} node ${pn_test_root}/javascript/codec.js) - add_test (javascript-message ${env_py} node ${pn_test_root}/javascript/message.js) -endif (BUILD_JAVASCRIPT) http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/0c9bb9ff/proton-c/bindings/CMakeLists.txt ---------------------------------------------------------------------- diff --git a/proton-c/bindings/CMakeLists.txt b/proton-c/bindings/CMakeLists.txt index 5362f92..233c09f 100644 --- a/proton-c/bindings/CMakeLists.txt +++ b/proton-c/bindings/CMakeLists.txt @@ -19,17 +19,7 @@ # Add bindings that do not require swig here - the directory name must be the same as the binding name # See below for swig bindings -set(BINDINGS javascript cpp go) - -# Prerequisites for javascript. -# -# It uses a C/C++ to JavaScript cross-compiler called emscripten (https://github.com/kripken/emscripten). Emscripten takes C/C++ -# and compiles it into a highly optimisable subset of JavaScript called asm.js (http://asmjs.org/) that can be -# aggressively optimised and run at near-native speed (usually between 1.5 to 10 times slower than native C/C++). -find_package(Emscripten) -if (EMSCRIPTEN_FOUND) - set (DEFAULT_JAVASCRIPT ON) -endif (EMSCRIPTEN_FOUND) +set(BINDINGS cpp go) if (CMAKE_CXX_COMPILER) set (DEFAULT_CPP ON) @@ -49,7 +39,7 @@ endif (GO_EXE) if(SWIG_FOUND) # Add any new swig bindings here - the directory name must be the same as the binding name - list(APPEND BINDINGS python ruby php perl) + list(APPEND BINDINGS python ruby) include(UseSWIG) @@ -58,11 +48,6 @@ if(SWIG_FOUND) # All swig modules should include ${BINDING_DEPS} in swig_link_libraries set (BINDING_DEPS qpid-proton) - # If swig version is 3.0 or greater then we can build some additional bindings - if (${SWIG_VERSION} VERSION_GREATER 3.0 OR ${SWIG_VERSION} VERSION_EQUAL 3.0) - list(APPEND SWIG_BINDINGS node) - endif() - # Add a block here to detect the prerequisites to build each language binding: # # If the prerequisites for the binding are present set a variable called @@ -79,26 +64,6 @@ if(SWIG_FOUND) if (RUBY_FOUND) set (DEFAULT_RUBY ON) endif (RUBY_FOUND) - - # Prerequites for PHP: - # For now, assume PHP support if the 'php-config' tool is present. - # @todo: allow user to specify which php-config if multiple PHP sources installed! - find_program(PHP_CONFIG_EXE php-config) - if (PHP_CONFIG_EXE) - find_program(PHP_EXE php) - mark_as_advanced (PHP_EXE) - if (PHP_EXE) - set (DEFAULT_PHP ON) - endif (PHP_EXE) - endif (PHP_CONFIG_EXE) - mark_as_advanced (PHP_CONFIG_EXE) - - # Prerequisites for Perl: - include(ProtonFindPerl) - if (PERLLIBS_FOUND) - set (DEFAULT_PERL ON) - endif (PERLLIBS_FOUND) - endif() http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/0c9bb9ff/proton-c/bindings/javascript/CMakeLists.txt ---------------------------------------------------------------------- diff --git a/proton-c/bindings/javascript/CMakeLists.txt b/proton-c/bindings/javascript/CMakeLists.txt deleted file mode 100644 index c81a2ad..0000000 --- a/proton-c/bindings/javascript/CMakeLists.txt +++ /dev/null @@ -1,279 +0,0 @@ -# -# Licensed to the Apache Software Foundation (ASF) under one -# or more contributor license agreements. See the NOTICE file -# distributed with this work for additional information -# regarding copyright ownership. The ASF licenses this file -# to you under the Apache License, Version 2.0 (the -# "License"); you may not use this file except in compliance -# with the License. You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, -# software distributed under the License is distributed on an -# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -# KIND, either express or implied. See the License for the -# specific language governing permissions and limitations -# under the License. -# - -# This file allows cross-compiling of proton to JavaScript using emscripten -# (https://github.com/kripken/emscripten). As it is really a cross-compilation -# (as opposed to a binding like with swig) the approach is rather different and -# somewhat replicates the main build in the proton-c/CMakeLists.txt using quite -# a bit of "copy and paste reuse". -# TODO refactor this file (and proton-c/CMakeLists.txt) to keep the main -# compilation and cross-compilation consistent. - -message(STATUS "Found emscripten, using that to build JavaScript binding") - -# Find and install the node.js packages that we might need. We can assume that -# node.js itself is installed because Emscripten has a dependency on it. -find_package(NodePackages) - -# Describe the target OS we are building to - Emscripten mimics the Linux platform. -set(CMAKE_SYSTEM_NAME Linux) -set(CMAKE_SYSTEM_VERSION 1) -set(CMAKE_CROSSCOMPILING TRUE) - -# Specify the compiler to use for cross-compilation. -set(CMAKE_C_COMPILER "${EMCC}") - -# Don't do compiler autodetection, since we are cross-compiling. -include(CMakeForceCompiler) -CMAKE_FORCE_C_COMPILER("${CMAKE_C_COMPILER}" Clang) - -# The Proton default build type is RelWithDebInfo, but for JavaScript the C debug -# mechanism is irrelevant. If Debug is explicitly set we turn off optimisations -# and don't run the closure compiler so any error/profiling messages are readable. -if (CMAKE_BUILD_TYPE STREQUAL "Debug") - message(STATUS "JavaScript build type is \"Debug\"") -else() - set(CMAKE_BUILD_TYPE Release) - message(STATUS "JavaScript build type is \"Release\"") - set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -O3") - set(EMSCRIPTEN_LINK_OPTIMISATIONS "-O2 --closure 1") -endif() - -# From this point we should be using emscripten compilation tools. -message(STATUS "emscripten compilation environment:") -message(STATUS "CMAKE_C_COMPILER: ${CMAKE_C_COMPILER}") - - -# Set this to the proton-c directory, we're cross-compiling code from there. -set(PN_PATH ${CMAKE_SOURCE_DIR}/proton-c) - - -# TODO the OpenSSL stuff won't work for emscripten by default. It might well be -# possible to compile it from source using emscripten (that's the standard practice -# for libraries with emscripten) see https://github.com/kripken/emscripten/wiki/FAQ -# "Q. How do I link against system libraries like SDL, boost, etc.?" -# Though it might be more natural to simply use a TLS protected wss:// WebSocket URL. -# set(pn_ssl_impl src/ssl/openssl.c) -# set(SSL_LIB ${OPENSSL_LIBRARIES}) -set(pn_ssl_impl ${PN_PATH}/src/ssl/ssl_stub.c) - -# emscripten is Linux like so use the posix impls. -set(pn_io_impl ${PN_PATH}/src/posix/io.c) -set(pn_selector_impl ${PN_PATH}/src/posix/selector.c) - -CHECK_LIBRARY_EXISTS (uuid uuid_generate "" UUID_GENERATE_IN_UUID) -if (UUID_GENERATE_IN_UUID) - set (UUID_LIB uuid) -endif (UUID_GENERATE_IN_UUID) - -# Generate encodings.h and protocol.h -# It may be possible to use the ones generated for the main proton-c build but -# qpid-proton-core has a dependency on the generated files, so I'm not sure if -# it'll work without a command that can be run as a dependency. Probably best -# do it this way when cross-compiling - though more copy'n'paste -add_custom_command( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/encodings.h - COMMAND python ${PN_PATH}/env.py PYTHONPATH=${PN_PATH} python ${PN_PATH}/src/codec/encodings.h.py > ${CMAKE_CURRENT_BINARY_DIR}/encodings.h - DEPENDS ${PN_PATH}/src/codec/encodings.h.py - ) - -add_custom_command( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/protocol.h - COMMAND python ${PN_PATH}/env.py PYTHONPATH=${PN_PATH} python ${PN_PATH}/src/protocol.h.py > ${CMAKE_CURRENT_BINARY_DIR}/protocol.h - DEPENDS ${PN_PATH}/src/protocol.h.py - ) - -set(COMPILE_WARNING_FLAGS "-Werror -Wall -pedantic-errors -Wno-comment -Wno-warn-absolute-paths") - -# Explicitly set PLATFORM_DEFINITIONS to Linux ones for emscripten as we don't -# want to inadvertently use Windows versions if we happen to be cross-compiling -# from a Windows platform -set(PLATFORM_DEFINITIONS "USE_CLOCK_GETTIME;USE_UUID_GENERATE;USE_STRERROR_R;USE_ATOLL") - -# The following is largely a copy from the the main proton-c/CMakeLists.txt. -# The main difference is prefixing paths with ${PN_PATH}/ as we can't use a -# relative path from this CMakeLists.txt. - -set(qpid-proton-platform - ${pn_io_impl} - ${pn_selector_impl} - ${PN_PATH}/src/platform.c - ${pn_ssl_impl} - ) - -set(qpid-proton-core - ${PN_PATH}/src/object/object.c - ${PN_PATH}/src/object/list.c - ${PN_PATH}/src/object/map.c - ${PN_PATH}/src/object/string.c - ${PN_PATH}/src/object/iterator.c - ${PN_PATH}/src/object/record.c - - ${PN_PATH}/src/log.c - ${PN_PATH}/src/util.c - ${PN_PATH}/src/url.c - ${PN_PATH}/src/error.c - ${PN_PATH}/src/buffer.c - ${PN_PATH}/src/parser.c - ${PN_PATH}/src/scanner.c - ${PN_PATH}/src/types.c - - ${PN_PATH}/src/framing/framing.c - - ${PN_PATH}/src/codec/codec.c - ${PN_PATH}/src/codec/decoder.c - ${PN_PATH}/src/codec/encoder.c - - ${PN_PATH}/src/dispatcher/dispatcher.c - ${PN_PATH}/src/engine/engine.c - ${PN_PATH}/src/events/event.c - ${PN_PATH}/src/transport/autodetect.c - ${PN_PATH}/src/transport/transport.c - ${PN_PATH}/src/message/message.c - ${PN_PATH}/src/sasl/sasl.c - ${PN_PATH}/src/sasl/none_sasl.c - - ${PN_PATH}/src/messenger/messenger.c - ${PN_PATH}/src/messenger/subscription.c - ${PN_PATH}/src/messenger/store.c - ${PN_PATH}/src/messenger/transform.c - ${PN_PATH}/src/selectable.c - - ${CMAKE_CURRENT_BINARY_DIR}/encodings.h - ${CMAKE_CURRENT_BINARY_DIR}/protocol.h - ) - -set_source_files_properties( - ${qpid-proton-core} - PROPERTIES - COMPILE_FLAGS "${COMPILE_WARNING_FLAGS} ${COMPILE_LANGUAGE_FLAGS}" - ) - -set_source_files_properties( - ${qpid-proton-platform} - PROPERTIES - COMPILE_FLAGS "${COMPILE_WARNING_FLAGS} ${COMPILE_PLATFORM_FLAGS}" - COMPILE_DEFINITIONS "${PLATFORM_DEFINITIONS}" - ) - -# Compile Proton into LLVM bitcode which will be used later in the linking stage -# of add_executable for compilation into Javascript. -add_library( - qpid-proton-bitcode SHARED - - ${qpid-proton-core} - ${qpid-proton-platform} - ) - -set_target_properties( - qpid-proton-bitcode - PROPERTIES - VERSION "${PN_LIB_LEGACY_VERSION}" - SOVERSION "${PN_LIB_LEGACY_MAJOR_VERSION}" - LINK_FLAGS "${CATCH_UNDEFINED}" - ) -target_link_libraries(qpid-proton-bitcode) - - -# Compile the send-async.c and recv-async.c examples into JavaScript -include_directories(${Proton_SOURCE_DIR}/examples/c/include) -add_executable(send-async.js ${Proton_SOURCE_DIR}/examples/c/messenger/send-async.c) -target_link_libraries(send-async.js qpid-proton-bitcode) - -add_executable(recv-async.js ${Proton_SOURCE_DIR}/examples/c/messenger/recv-async.c) -target_link_libraries(recv-async.js qpid-proton-bitcode) - -set_target_properties( - send-async.js recv-async.js - PROPERTIES - COMPILE_FLAGS "${COMPILE_WARNING_FLAGS} ${COMPILE_PLATFORM_FLAGS}" - RUNTIME_OUTPUT_DIRECTORY examples - DEPENDS ws - - LINK_FLAGS "-s \"WEBSOCKET_SUBPROTOCOL='AMQPWSB10'\" -${EMSCRIPTEN_LINK_OPTIMISATIONS}" - ) - -# Build the main JavaScript library called proton-messenger.js -add_executable(proton-messenger.js binding.c) -target_link_libraries(proton-messenger.js qpid-proton-bitcode ${UUID_LIB}) - -set_target_properties( - proton-messenger.js - PROPERTIES - COMPILE_FLAGS "${COMPILE_WARNING_FLAGS} ${COMPILE_PLATFORM_FLAGS}" - - # The --memory-init-file 0 stops emscripten emitting a separate memory - # initialization file, if this was enabled it makes packaging harder as - # applications would expect proton-messenger.js.mem to be served too. It's even - # more fiddly with node.js packages. This behaviour might be reinstated if the - # packaging mechanism improves. - - LINK_FLAGS "-s \"EXPORT_NAME='proton'\" -s \"WEBSOCKET_SUBPROTOCOL='AMQPWSB10'\" ${EMSCRIPTEN_LINK_OPTIMISATIONS} --memory-init-file 0 --pre-js ${CMAKE_CURRENT_SOURCE_DIR}/binding-open.js --pre-js ${CMAKE_CURRENT_SOURCE_DIR}/module.js --pre-js ${CMAKE_CURRENT_SOURCE_DIR}/error.js --pre-js ${CMAKE_CURRENT_SOURCE_DIR}/messenger.js --pre-js ${CMAKE_CURRENT_SOURCE_DIR}/subscription.js --pre-js ${CMAKE_CURRENT_SOURCE_DIR}/message.js --pre-js ${CMAKE_CURRENT_SOURCE_DIR}/data.js --pre-js ${CMAKE_CURRENT_SOURCE_DIR}/data-uuid.js --pre-js ${CMAKE_CURRENT_SOURCE_DIR}/data-symbol.js --pre-js ${CMAKE_CURRENT_SOURCE_DIR}/data-described.js --pre-js ${CMAKE_CURRENT_SOURCE_DIR}/data-array.js --pre-js ${CMAKE_CURRENT_SOURCE_DIR}/data-typed-number.js --pre-js ${CMAKE_CURRENT_SOURCE_DIR}/data-long.js --pre-js ${CMAKE_CURRENT_SOURCE_DIR}/data-binary.js --post-js ${CMAKE_CURRENT_SOURCE_DIR}/binding-close.js -s DEFAULT_LIBRARY_FUNCS_TO_INCLUDE=\"[]\" -s EXPORTED_FUNCTIONS=\"['_pn_get_version_major', '_ pn_get_version_minor', '_pn_uuid_generate', '_pn_bytes', '_pn_error_text', '_pn_code', '_pn_messenger', '_pn_messenger_name', '_pn_messenger_set_blocking', '_pn_messenger_free', '_pn_messenger_errno', '_pn_messenger_error', '_pn_messenger_get_outgoing_window', '_pn_messenger_set_outgoing_window', '_pn_messenger_get_incoming_window', '_pn_messenger_set_incoming_window', '_pn_messenger_start', '_pn_messenger_stop', '_pn_messenger_stopped', '_pn_messenger_subscribe', '_pn_messenger_put', '_pn_messenger_status', '_pn_messenger_buffered', '_pn_messenger_settle', '_pn_messenger_outgoing_tracker', '_pn_messenger_recv', '_pn_messenger_receiving', '_pn_messenger_get', '_pn_messenger_incoming_tracker', '_pn_messenger_incoming_subscription', '_pn_messenger_accept', '_pn_messenger_reject', '_pn_messenger_outgoing', '_pn_messenger_incoming', '_pn_messenger_route', '_pn_messenger_rewrite', '_pn_messenger_set_passive', '_pn_messenger_selectable', '_pn_subscription_get_context', '_pn_subscription_ set_context', '_pn_subscription_address', '_pn_message', '_pn_message_id', '_pn_message_correlation_id', '_pn_message_free', '_pn_message_errno', '_pn_message_error', '_pn_message_clear', '_pn_message_is_inferred', '_pn_message_set_inferred', '_pn_message_is_durable', '_pn_message_set_durable', '_pn_message_get_priority', '_pn_message_set_priority', '_pn_message_get_ttl', '_pn_message_set_ttl', '_pn_message_is_first_acquirer', '_pn_message_set_first_acquirer', '_pn_message_get_delivery_count', '_pn_message_set_delivery_count', '_pn_message_get_user_id', '_pn_message_set_user_id', '_pn_message_get_address', '_pn_message_set_address', '_pn_message_get_subject', '_pn_message_set_subject', '_pn_message_get_reply_to', '_pn_message_set_reply_to', '_pn_message_get_content_type', '_pn_message_set_content_type', '_pn_message_get_content_encoding', '_pn_message_set_content_encoding', '_pn_message_get_expiry_time', '_pn_message_set_expiry_time', '_pn_message_get_creation_time', '_pn_message_se t_creation_time', '_pn_message_get_group_id', '_pn_message_set_group_id', '_pn_message_get_group_sequence', '_pn_message_set_group_sequence', '_pn_message_get_reply_to_group_id', '_pn_message_set_reply_to_group_id', '_pn_message_encode', '_pn_message_decode', '_pn_message_instructions', '_pn_message_annotations', '_pn_message_properties', '_pn_message_body', '_pn_data', '_pn_data_free', '_pn_data_error', '_pn_data_errno', '_pn_data_clear', '_pn_data_rewind', '_pn_data_next', '_pn_data_prev', '_pn_data_enter', '_pn_data_exit', '_pn_data_lookup', '_pn_data_narrow', '_pn_data_widen', '_pn_data_type', '_pn_data_encode', '_pn_data_decode', '_pn_data_put_list', '_pn_data_put_map', '_pn_data_put_array', '_pn_data_put_described', '_pn_data_put_null', '_pn_data_put_bool', '_pn_data_put_ubyte', '_pn_data_put_byte', '_pn_data_put_ushort', '_pn_data_put_short', '_pn_data_put_uint', '_pn_data_put_int', '_pn_data_put_char', '_pn_data_put_ulong', '_pn_data_put_long', '_pn_data_put_timestamp', '_pn _data_put_float', '_pn_data_put_double', '_pn_data_put_decimal32', '_pn_data_put_decimal64', '_pn_data_put_decimal128', '_pn_data_put_uuid', '_pn_data_put_binary', '_pn_data_put_string', '_pn_data_put_symbol', '_pn_data_get_list', '_pn_data_get_map', '_pn_data_get_array', '_pn_data_is_array_described', '_pn_data_get_array_type', '_pn_data_is_described', '_pn_data_is_null', '_pn_data_get_bool', '_pn_data_get_ubyte', '_pn_data_get_byte', '_pn_data_get_ushort', '_pn_data_get_short', '_pn_data_get_uint', '_pn_data_get_int', '_pn_data_get_char', '_pn_data_get_ulong', '_pn_data_get_long', '_pn_data_get_timestamp', '_pn_data_get_float', '_pn_data_get_double', '_pn_data_get_decimal32', '_pn_data_get_decimal64', '_pn_data_get_decimal128', '_pn_data_get_uuid', '_pn_data_get_binary', '_pn_data_get_string', '_pn_data_get_symbol', '_pn_data_copy', '_pn_data_format', '_pn_data_dump', '_pn_selectable_readable', '_pn_selectable_is_reading', '_pn_selectable_writable', '_pn_selectable_is_writing', '_ pn_selectable_is_terminal', '_pn_selectable_get_fd', '_pn_selectable_free']\"" - ) - -# This command packages up the compiled proton-messenger.js into a node.js package -# called qpid-proton-messenger and copies it to the <proton>/node_modules directory. -# This allows the node.js test and example programs to do: -# var proton = require("qpid-proton-messenger"); -add_custom_command( - TARGET proton-messenger.js - COMMAND ${CMAKE_COMMAND} - -E copy_directory - ${CMAKE_CURRENT_SOURCE_DIR}/qpid-proton-messenger - ${PROJECT_SOURCE_DIR}/node_modules/qpid-proton-messenger - COMMAND ${CMAKE_COMMAND} - -E copy - ${CMAKE_CURRENT_BINARY_DIR}/proton-messenger.js - ${PROJECT_SOURCE_DIR}/node_modules/qpid-proton-messenger/lib - COMMENT "Building qpid-proton-messenger package for node.js" -) - -# The cleanall target removes the qpid-proton-messenger package from <proton>/node_modules -add_custom_target( - cleanall - COMMAND echo "CLEAN NODE MODULES" - COMMAND ${CMAKE_COMMAND} - -E remove_directory - ${PROJECT_SOURCE_DIR}/node_modules/qpid-proton-messenger -) - -# If the docs target is specified and the jsdoc3 package for node.js has been -# installed then build the JavaScript API documentation. -if (NODE_JSDOC_FOUND) - set(JSDOC_EXE ${PROJECT_SOURCE_DIR}/node_modules/.bin/jsdoc) - - message(STATUS "Documentation Enabled. Using ${JSDOC_EXE} to build JavaScript docs") - add_custom_target(docs-js COMMAND ${JSDOC_EXE} - -d ${CMAKE_CURRENT_BINARY_DIR}/html - ${CMAKE_CURRENT_SOURCE_DIR}/module.js - ${CMAKE_CURRENT_SOURCE_DIR}/error.js - ${CMAKE_CURRENT_SOURCE_DIR}/messenger.js - ${CMAKE_CURRENT_SOURCE_DIR}/subscription.js - ${CMAKE_CURRENT_SOURCE_DIR}/message.js - ${CMAKE_CURRENT_SOURCE_DIR}/data.js - ${CMAKE_CURRENT_SOURCE_DIR}/data-uuid.js - ${CMAKE_CURRENT_SOURCE_DIR}/data-symbol.js - ${CMAKE_CURRENT_SOURCE_DIR}/data-described.js - ${CMAKE_CURRENT_SOURCE_DIR}/data-array.js - ${CMAKE_CURRENT_SOURCE_DIR}/data-typed-number.js - ${CMAKE_CURRENT_SOURCE_DIR}/data-long.js - ${CMAKE_CURRENT_SOURCE_DIR}/data-binary.js) - add_dependencies(docs docs-js) -endif (NODE_JSDOC_FOUND) - http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/0c9bb9ff/proton-c/bindings/javascript/LICENSE ---------------------------------------------------------------------- diff --git a/proton-c/bindings/javascript/LICENSE b/proton-c/bindings/javascript/LICENSE deleted file mode 100644 index 6b0b127..0000000 --- a/proton-c/bindings/javascript/LICENSE +++ /dev/null @@ -1,203 +0,0 @@ - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/0c9bb9ff/proton-c/bindings/javascript/README ---------------------------------------------------------------------- diff --git a/proton-c/bindings/javascript/README b/proton-c/bindings/javascript/README deleted file mode 100644 index 9ec37d0..0000000 --- a/proton-c/bindings/javascript/README +++ /dev/null @@ -1,426 +0,0 @@ -Qpid Proton JavaScript Language Bindings -======================================== - -The code contained herein provides JavaScript language bindings for working -with the Qpid Proton AMQP 1.0 protocol engine and messenger library. - -Important Note - Modern Browser Needed -====================================== - -The JavaScript binding requires ArrayBuffer/TypedArray and WebSocket support. -Both of these are available in most "modern" browser versions. The author has -only tried running on FireFox and Chrome, though recent Safari, Opera and IE10+ -*should* work too - YMMV. It might be possible to polyfill for older browsers -but the author hasn't tried this. - -Important Note - WebSocket Transport!!! -======================================= - -Before going any further it is really important to realise that the JavaScript -bindings to Proton are somewhat different to the bindings for other languages -because of the restrictions of the execution environment. In particular it is -very important to note that the JavaScript bindings by default use a WebSocket -transport and not a TCP transport, so whilst it's possible to create Server style -applications that clients can connect to (e.g. recv.js and send.js) note that: - -JavaScript clients cannot *directly* talk to "normal" AMQP applications such as -qpidd or (by default) the Java Broker because they use a standard TCP transport. - -This is a slightly irksome issue, but there's no getting away from it because -it's a security restriction imposed by the browser environment. - - -At the moment even for Node.js we are limited to using a WebSocket transport, but -it is on the author's "TODO" list to look at providing a means to use either a -WebSocket transport or a native TCP transport (via node's net library). It should -also be possible to use native TCP for Chrome "packaged apps", but again this is -only on the TODO list so if you want to talk to a "normal" AMQP application you -must live with the WebSocket constraints. - -Option 1. proxy from WebSockets to TCP sockets. The application -<proton>/examples/messenger/javascript/proxy.js -is a simple Node.js WebSocket<->TCP Socket proxy, simply doing: - -node proxy.js - -will stand up a proxy listening by default on WebSocket port 5673 and forwarding -to TCP port 5672 (this is configurable, for options do: node proxy.js -h) - -Rather than using a stand-alone proxy it is possible to have applications stand -up their own proxy (where lport = listen port, thost = target host and -tport = target port): - -var proxy = require('./ws2tcp.js'); -proxy.ws2tcp(lport, thost, tport); - -For talking to the C++ broker unfortunately proxying is currently the only option -as qpidd does not have a WebSocket transport. - -Option 2. The Java Broker's WebSocket transport. -Recent releases of the Qpid Java Broker provide a native WebSocket transport which -means that the JavaScript binding can talk to it with no additional requirements. -It is necessary to configure the Java Broker as the WebSocket transport is not -enabled by default. In <qpid-work>/config.json in the "ports" array you need to add: - -{ - "authenticationProvider" : "passwordFile", - "name" : "AMQP-WS", - "port" : "5673", - "transports" : [ "WS" ] -} - -This sets the JavaBroker to listen on WebSocket port 5673 similar to the proxy. - - -One gotcha that still bites the author *** DO NOT FORGET *** that you will be -using ports that you are not used to!! If you are not connecting check that the -proxy is running and that you are specifying the right ports. I still mess up :-( - -WebRTC Transport -================ - -A WebRTC Transport is supported by emscripten, though the author has not tried it. -If you wan to play with this you are very much on your own at the moment YMMV. - -This is configured by adding to the LINK_FLAGS in CMakeLists.txt --s \"SOCKET_WEBRTC=1\" - - /* WebRTC sockets supports several options on the Module object. - - * Module['host']: true if this peer is hosting, false otherwise - * Module['webrtc']['broker']: hostname for the p2p broker that this peer should use - * Module['webrtc']['session']: p2p session for that this peer will join, or undefined if this peer is hosting - * Module['webrtc']['hostOptions']: options to pass into p2p library if this peer is hosting - * Module['webrtc']['onpeer']: function(peer, route), invoked when this peer is ready to connect - * Module['webrtc']['onconnect']: function(peer), invoked when a new peer connection is ready - * Module['webrtc']['ondisconnect']: function(peer), invoked when an existing connection is closed - * Module['webrtc']['onerror']: function(error), invoked when an error occurs - */ - -If you wanted to play with these you'd likely have to tweak the module.js code in -<proton>/proton-c/bindings/javascript - -The emscripten documentation is a bit light on the WebRTC Transport too, though - -emscripten/tests/test_sockets.py -emscripten/tests/sockets/webrtc_host.c -emscripten/tests/sockets/webrtc_peer.c -emscripten/tests/sockets/p2p/broker/p2p-broker.js -emscripten/tests/sockets/p2p/client/p2p-client.js - -Look like they provide a starting point. -Very much TODO...... - - -Creating The Bindings -===================== - -To generate the JavaScript bindings we actually cross-compile from proton-c - -You will need to have emscripten (https://github.com/kripken/emscripten) installed -to do the cross-compilation and in addition you will require a few things that -emscripten itself depends upon. - -http://kripken.github.io/emscripten-site/docs/building_from_source/index.html#installing-from-source -http://kripken.github.io/emscripten-site/docs/building_from_source/toolchain_what_is_needed.html -provide instructions for installing emscripten and the "fastcomp" LLVM backend. -This approach lets users use the "bleeding edge" version of emscripten on the -"incoming" branch (pretty much analogous to building qpid/proton off svn trunk). -This is the approach that the author of the JavaScript Bindings tends to use. - - -http://kripken.github.io/emscripten-site/docs/getting_started/downloads.html -provides some fairly easy to follow instructions for getting started on several -platforms the main dependencies are as follows (on Windows the SDK includes these): - -* The Emscripten code, from github (git clone git://github.com/kripken/emscripten.git). -* LLVM with Clang. Emscripten uses LLVM and Clang, but at the moment the JavaScript - back-end for LLVM is off on a branch so you can't use a stock LLVM/Clang. - http://kripken.github.io/emscripten-site/docs/building_from_source/LLVM-Backend.html - http://kripken.github.io/emscripten-site/docs/building_from_source/building_fastcomp_manually_from_source.html#building-fastcomp-from-source - has lots of explanation and some easy to follow instructions for downloading - and building fastcomp -* Node.js (0.8 or above; 0.10.17 or above to run websocket-using servers in node) -* Python 2.7.3 -* Java is required in order to use the Closure Compiler to minify the code. - - -If you haven't run Emscripten before it's a good idea to have a play with the -tutorial here: -http://kripken.github.io/emscripten-site/docs/getting_started/Tutorial.html - - - -when you are all set up with emscripten and have got the basic tests in the -tutorial running building Proton should be simple, simply go to the Proton root -directory and follow the main instructions in the README there, in precis (from -the root directory) it's: - - mkdir build - cd build - cmake .. - make - -and you should be all set, to test it's all working do (from the build directory): - cd proton-c/bindings/javascript/examples - - node recv-async.js - -in one window and - - node send-async.js - -in another. - -These examples are actually JavaScript applications that have been directly -compiled from recv-async.c and send-async.c in <proton>/examples/messenger/c -if you'd prefer to write applications in C and compile them to JavaScript that -is a perfectly valid approach and these examples provide a reasonable starting -point for doing so. - -Documentation -============= - -When you've successfully got a working build do: - - make docs - -Which will make all of the proton documentation including the JavaScript docs. -If successful the JSDoc generated documentation should be found here: - -<proton>/build/proton-c/bindings/javascript/html/index.html - - -Using "native" JavaScript -========================= - -The examples in <proton>/examples/messenger/javascript are the best starting point. - -In practice the examples follow a fairly similar pattern to the Python bindings -the most important thing to bear in mind though is that JavaScript is completely -asynchronous/non-blocking, which can catch the unwary. - -An application follows the following (rough) steps: - -1. (optional) Set the heap size. -It's important to realise that most of the library code is compiled C code and -the runtime uses a "virtual heap" to support the underlying malloc/free. This is -implemented internally as an ArrayBuffer with a default size of 16777216. - -To allocate a larger heap an application must set the PROTON_TOTAL_MEMORY global. -In Node.js this would look like (see send.js): -PROTON_TOTAL_MEMORY = 50000000; // Note no var - it needs to be global. - -In a browser it would look like (see send.html): -<script type="text/javascript">PROTON_TOTAL_MEMORY = 50000000;</script> - -2. Load the library and create a message and messenger. -In Node.js this would look like (see send.js): -var proton = require("qpid-proton-messenger"); -var message = new proton.Message(); -var messenger = new proton.Messenger(); - -In a browser it would look like (see send.html): -<script type="text/javascript" src="../../../node_modules/qpid-proton-messenger/lib/proton-messenger.js"></script> - -<script type="text/javascript"> -var message = new proton.Message(); -var messenger = new proton.Messenger(); -.... - -3. Set up event handlers as necessary. - -messenger.on('error', <error callback>); -messenger.on('work', <work callback>); -messenger.on('subscription', <subscription callback>); - - -The work callback is triggered on WebSocket events, so in general you would use -this to send and receive messages, for example in recv.js we have: - -var pumpData = function() { - while (messenger.incoming()) { - var t = messenger.get(message); - - console.log("Address: " + message.getAddress()); - console.log("Subject: " + message.getSubject()); - - // body is the body as a native JavaScript Object, useful for most real cases. - //console.log("Content: " + message.body); - - // data is the body as a proton.Data Object, used in this case because - // format() returns exactly the same representation as recv.c - console.log("Content: " + message.data.format()); - - messenger.accept(t); - } -}; - -messenger.on('work', pumpData); - - -The subscription callback is triggered when the address provided in a call to -messenger.subscribe(<address>); - -Gets resolved. An example of its usage can be found in qpid-config.js which is -a fully functioning and complete port of the python qpid-config tool. It also -illustrates how to do asynchronous request/response based applications. - -Aside from the asynchronous aspects the rest of the API is essentially the same -as the Python binding aside from minor things such as camel casing method names etc. - -Serialisation/Deserialization, Types etc. -========================================= - -The JavaScript binding tries to be as simple, intuitive and natural as possible -so when sending a message all native JavaScript types including Object literals -and Arrays are transparently supported, for example. - -var message = new proton.Message(); -message.setAddress('amqp://localhost'); -message.setSubject('UK.NEWS'); -message.body = ['Rod', 'Jane', 'Freddy', {cat: true, donkey: 'hee haw'}]; - - -The main thing to bear in mind is that (particularly for sending messages) we -may need to use "adapters" to make sure values are correctly interpreted and -encoded to the correct type in the AMQP type system. This is especially important -when interoperating with a peer written in a strongly typed language (C/C++/Java). - -Some examples of available types follow: - -// UUID -message.body = new proton.Data.Uuid(); - -// AMQP Symbol -message.body = new proton.Data.Symbol("My Symbol"); - -// Binary data (created from a gibberish String in this case). -message.body = new proton.Data.Binary("Monkey BathпогÑÐ¾Ð¼Ð·Ñ Ñвбнм"); - -// Binary data (Get a Uint8Array view of the data and directly access that). -message.body = new proton.Data.Binary(4); -var buffer = message.body.getBuffer(); -buffer[0] = 65; -buffer[1] = 77; -buffer[2] = 81; -buffer[3] = 80; - -// Binary Data (Created from an Array, you can use an ArrayBuffer/TypedArray too). -message.body = new proton.Data.Binary([65, 77, 81, 80]); - - -Note that the implementation of proton.Data.Binary tries to minimise copying so -it accesses the internal emscripten heap *directly* this requires memory management -which is mostly handled transparently, but users need to be aware that the -underlying memory is "owned" by the Message Object, so if Binary data needs to -be maintained after the next call to messenger.get(message); it must be -*explicitly* copied. For more detail do "make docs" and see: -<proton>/build/proton-c/bindings/javascript/html/proton.Data.Binary.html - - -// AMQP Described (value, descriptor) -message.body = new proton.Data.Described('persian, 'com.cheezburger.icanhas'); - -// AMQP Timestamp maps to native JavaScript Date. -message.body = new Date(); - -// Various AMQP Array examples. -message.body = new proton.Data.Array('INT', [1, 3, 5, 7], "odd numbers"); -message.body = new proton.Data.Array('UINT', [1, 3, 5, 7], "odd"); -message.body = new proton.Data.Array('ULONG', [1, 3, 5, 7], "odd"); -message.body = new proton.Data.Array('FLOAT', [1, 3, 5, 7], "odd"); -message.body = new proton.Data.Array('STRING', ["1", "3", "5", "7"], "odd"); - -// A JavaScript TypedArray will map directly to and from an AMQP Array of the -// appropriate type (Internally sets a descriptor of 'TypedArray'). -message.body = new Uint8Array([1, 3, 5, 7]); - -// UUID Array -message.body = new proton.Data.Array('UUID', [new proton.Data.Uuid(), new proton.Data.Uuid(), new proton.Data.Uuid(), new proton.Data.Uuid()], "unique"); - -// Null -message.body = null; - -// Boolean -message.body = true; - -// Native JavaScript Array maps to an AMQP List -message.body = ['Rod', 'Jane', 'Freddy']; - -// Native JavaScript Object maps to an AMQP Map -message.body = ['Rod', 'Jane', 'Freddy', {cat: true, donkey: 'hee haw'}]; - -// JavaScript only has a "number" type so the binding provides "decorator" -// methods added to the JavaScript Number class. To access this from number -// primitives it is necessary to either use braces or use a "double dot" so that -// the interpreter can disambiguate from a simple decimal point. The binding will -// attempt to use the correct type such that message.body = 2147483647; would be -// sent as an AMQP integer, but because of the way JavaScript coerces integers -// message.body = 2147483647.0; would also be sent as an AMQP integer because -// 2147483647.0 gets transparently converted to 2147483647 by the interpreter, so -// to explicitly send this as an AMQP float we'd need to do: -// message.body = 2147483647.0.float(); - -// Some more number examples: -message.body = 66..char(); // char - note double dot. (66).char(); works too. -message.body = 2147483647; // int -message.body = -2147483649; // long -message.body = 12147483649; // long -message.body = (12147483649).long(); // long -message.body = (17223372036854778000).ulong(); // ulong -message.body = (121474.836490).float(); // float -message.body = 12147483649.0.float(); // float -message.body = (4294967296).uint(); // uint -message.body = (255).ubyte(); // ubyte - -Note too that floats are subject to a loss of precision - - -Fortunately most of these quirks only affect serialisation.when the binding -receives a message it will attempt to decode it into the most "natural" native -JavaScript type. - - -One additional decoding "quirk" can be caused by C++ qpid::messaging clients. It -is unfortunately quite common for C++ clients to incorrectly encode Strings as -AMQP Binary by neglecting to provide an encoding. The QMF Management Agent is one -such culprit. This is a bit of a pain, especially because of proton.Data.Binary -memory management quirks and having to remember to explicitly copy the data -on each call to messenger.get(message); In order to cater for this an overloaded -messenger.get(message, true); has been provided. Setting the second parameter to -true forces any received Binary payloads to be decoded as Strings. If you know -that producers might behave in this way and you are not expecting any "real" -Binary data from the producer this convenience mechanism results in nice clean -JavaScript Objects being received and is extremely useful for things like QMF. - -JSON -==== - -As well as allowing native JavaScript Objects and Arrays to be transparently -serialised and deserialized via the AMQP type system it is also possible to -serialise/deserialize as JSON. - -message.setAddress('amqp://localhost'); -message.setContentType('application/json'); -message.body = {array: [1, 2, 3, 4], object: {name: "John Smith", age: 65}}; - -On the wire the above will be encoded as an opaque binary in an AMQP data section -but will be deserialized into a JavaScript Object in exactly the same was as the -previous examples that use the AMQP type system. - -SUPPORT -======= - -To report bugs in the bindings, or to request an enhancement, please file -a tracker request: - - https://issues.apache.org/jira/browse/PROTON - -The main support channel is the qpid-users mailing list, see: - - http://qpid.apache.org/discussion.html#mailing-lists - -You can also directly interact with the development team and other users -in the #qpid channel on irc.freenode.net. - --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
