NetUtil -- version 0.39 (built 12-jun-11) --
statement
NetUtil is a compact and efficient java library for sending and receiving messages using the OpenSoundControl (OSC) protocol. It is (C)opyright 2004–2011 by Hanns Holger Rutz. All rights reserved. NetUtil is released under the GNU Lesser General Public License and comes with absolutely no warranties. To contact the author, send an email to contact at sciss.de
For project status, API and current version, visit www.sciss.de/netutil.
requirements / installation
NetUtil requires a Java(tm) 1.4+ environment. NetUtil has also been successfuly running on Android.
download
The current version can be downloaded here:
Either go to the regular download section for stable builds, or use SVN to grab the latest developer sourcecode version.
documentation
Documentation comes in the form of JavaDoc. The generate the docs, open a terminal, cd into the JCollider folder and run:
$ ant doc
compilation / usage
Please read the DevelopersNeeded note.
The source code can be compiled using Eclipse SDK 3.4+ (www.eclipse.org) and Apache Ant 1.6.5+ (ant.apache.org). The Eclipse project file is configured to run the regular Ant build file. You can make a clean build just with Ant from the terminal:
$ ant clean jar
$ ant test
The "test" will run with UDP server test, you can leave away that task. If you want a more compact build without debugging (line numbers) information, add -Ddebug=false to the ant call.
The final product will be a file build/NetUtil.jar which you can include in the classpath of your application.
The class de.sciss.net.test.NetUtilTest is supplied for simple testing routines that demonstrate the use of some of the classes (some of the examples printed in the API docs). Execute java -jar build/NetUtil.jar to learn about commandline options for running these examples. For more sophisticated examples of using the library, have a look at JCollider, Eisenkraut or SwingOSC.
interesting links
- www.opensoundcontrol.org : information about OSC specifications and implementations
- Illposed JavaOSC : another OSC library for Java
- oscP5 : OSC library for Processing
- flosc : OSC library (written in Java) for bridging OSC clients and Macromedia Flash
- jmDNS : automatic service discovery library for Java.
here is some sporadic list of projects which seem to use NetUtil. if you want to have your project added here, send me the links:
to-do / known issues
- add special client and server listeners so one can detect channels/connections opening and closing
- add helper classes (multi-server wrapper, message deferrer)
change history
v0.39 (jun 2011 - SVN rev. 23)
- OSCClient and OSCTransmitter creation: socket's IP defaults to "0.0.0.0" now instead of InetAddress.getLocalHost(). Allegedly that was responsible for an issue on Android.
v0.38 (may 2009 - SVN rev. 21)
- Removed makedoc.sh in favour of a doc ant target
v0.37 (may 2009 - SVN rev. 18)
- OSCServer creation: socket's IP defaults to "0.0.0.0" now instead of InetAddress.getLocalHost(); added tests
v0.36 (may 2009 - SVN rev. 16)
- Fixed bug in OSCReceiver.newUsing( DatagramChannel )
- Increased OSCPacketCodec.Atom visibility
- Fixed confusing error message with null OSC message arguments
- Fixed typo: OSCBundle.setTimeTagRow becomes setTimeTagRaw
- OSCReceiver creation: socket's IP defaults to "0.0.0.0" now instead of InetAddress.getLocalHost(), since this way messages both from localhost and loopback sockets are received.
v0.35 (apr 2008 - SVN rev. 6)
- Improved and fixed javadoc comments for OSCTransmitter, OSCReceiver, OSCClient, OSCServer
v0.34 (apr 2008 - SVN rev. 5)
- Added javadoc comments for OSCPacketCodec
v0.33 (jul 2007)
- Added separate OSCPacketCodec class and factory methods for OSCClient, OSCServer, OSCTransmitter, OSCReceiver, using this new codec. The codec allows to specify 64-bit primitives behaviour among others. The SpecificOSCMessage class was dropped.
- String ('s' type) argument decoding now follows the given codec. Default codec uses UTF-8 on all platforms.
- Bug fix in OSCTransmitter.newUsing( String, int ).
- Slightly increased decoding performance.
v0.32 (mar 2007)
- String ('s' type) argument decoding correctly uses platform default charset for ascii characters >127.
- using Eclipse and Ant now.
v0.31 (oct 2006)
- Allows "revivable" channels and clients. Improved TCP support.
v0.30 (oct 2006)
- Integration of TCP mode as alternative to UDP.
- This suggested API changes (see readme_api_changes.txt for details)
- New classes
OSCClient and OSCServer simplify the use of receivers and transmitters.
- Improved javadocs
v0.26 (jul 2006)
- Minor improvements in OSCReceiver
v0.25 (nov 2005)
- Bug fixes : decoding blob arguments
v0.24 (sep 2005)
- API change: the
OSCListener interface is modified to include the timetag of the incoming message.
- Bug fixes : byte boundary alignment of blobs, packet size calculation with blobs and nested messages.
- Small improvements (hexdump looks better + receiver thread catches runtime exceptions)
v0.22 (sep 2005)
- OSCMessage allows byte[] arguments which are encoded as a blob.
v0.2 (aug 2005)
OSCReceiver is accompanied by a new OSCTransmitter class which is really simple but saves you from typing the same five lines over and over again. Their common super class is AbstractOSCCommunicator which provides a dumpOSC method.- It turned out that binding an unbound channel in the
OSCReceiver constructor to "127.0.0.1" would silently disallow that channel to send messages outside the local computer. The behaviour has therefore changed to bind the channel to the loopback address only if the filter address is a loopback address (indicating usage on the local machine only), otherwise the local IP address is used.
v0.14 (aug 2005)
- OSCReceiver has a new contract of not allowing channels to be connected. This allows you to use the channel both for sending and receiving messages. Print messages have been added to OSCPacket and a debugDump method to OSCReceiver
v0.12 (jul 2005)
- tries to avoid a runtime error discovered on linux (sun jdk 1.5)
v0.11 (jun 2005)
- first version, an extract from meloncillo basically
java is a trademark of sun microsystems
i think mac os and xcode are trademarks of apple inc
windows is one of microsoft corp
jever is a trademark of some west german beer factory