Tutorials | Zipwhip's Blog

Zipwhip New User Sign Up Flag

February 22, 2012 2 Comments

At Zipwhip we like to keep it fun and nerdy. So, we decided to do something a bit whimsical every time we get a new sign up on our site. We purchased some hardware, put in a weekend of work, and now we have a flag hanging on the wall in the office that automatically goes up every time we get a new sign up on our site!

The flag is attached to a servo motor and an Arduino over ethernet . Each time we get the sign up event inside our cloud infrastructure, we send an HTTP command to the embedded web server running on the Arduino. The Arduino then sends the appropriate commands to the servo and UP POPS THE FLAG!

It’s a ton of fun to see something visual happen each time we get a new user.

The one concern is that we may have to build in a queue to the software that sends the signal to the Arduino. This is because we get quite a few sign ups. So much so, that we will get a lag between when the flag actually moves, and the exact time the sign up occurred. If the queues fill up too much or the lag gets too long, we will likely just reduce the size of our flag and make a wall of flags all moving independently.

Want to make your own? Below is a screenshot of (a.) the code inside the Arduino IDE (b.) the board diagram and (c.) the Arduino code to make it happen.

Here’s our bill of materials:

1 Yard of Orange Fabric. 100% Cotton. Joanne Fabrics. $2.
1 Bottle of Liquid Stitch. Joanne Fabrics. $6.
1 Wooden Dowel. Joanne Fabrics. $2.
1 Avery Light Fabric Inkjet Transfer Pack. Staples. $20.
1 Arduino. SparkFun.com. $29.
1 Arduino Ethernet Shield. SparkFun.com. $40.
1 Savox 400 oz-in SC-1256TG High Torque Titanium Gear Standard Digital Coreless Servo.
http://www.savoxusa.com
$80.
1 Power Adapter. 6V DC 2 Amp. Lynxmotion.com.
1 40’ Ethernet cable. Newegg.com. $2.
1 Ikea Akurum Harlig White Door as Mount. Ikea. $5.
8 Wood Screws. #10 size for servo. #2 size for Arduino. $5.

This is a screenshot of how you use the Arduino IDE to write your code. The free IDE is available at http://www.arduino.cc.

This is a Fritzing diagram of the Arduino main board and the Arduino Ethernet Shield combined with the servo wiring. The hardest part of getting this schematic to work is getting enough power to the servo without sending it through the Arduino control pins.

And finally here is the full code to run your own flag. We painstakingly perfected the code so you know it’s ready to go for your own use.

________________________________________________________________________________________________________

Web Server

A simple web server that shows the value of the analog input pins.
using an Arduino Wiznet Ethernet shield.

Circuit:
* Ethernet shield attached to pins 10, 11, 12, 13
* Analog inputs attached to pins A0 through A5 (optional)

// Sweep
// by BARRAGAN <http://barraganstudio.com>
// This example code is in the public domain.

// Zipwhip Sign Up Flag Codebase
// This code lets the Arduino operate a webserver. Whenever any
// request comes in to the server, it raises the flag. It’s quite
// simple. If too many requests are going to come in, the server is
// single-threaded so other requests have to wait. The sending process
// may want to instituate it’s own queuing system to solve for this.

#include <SPI.h>
#include <Ethernet.h>
#include <Servo.h>

Servo myservo; // create servo object to control a servo
// a maximum of eight servo objects can be created

int pos = 0; // variable to store the servo position
int startPos = 154;

// Enter a MAC address and IP address for your controller below.
// The IP address will be dependent on your local network:
byte mac[] = { 0xDA, 0xAD, 0xBA, 0xEA, 0xFE, 0xED };
IPAddress ip(192,168,1, 252);

// Initialize the Ethernet server library
// with the IP address and port you want to use
// (port 80 is default for HTTP):
EthernetServer server(80);
EthernetClient client;

void setup()
{

//Serial.begin(9600); // open the serial port at 9600 bps:

// start the Ethernet connection and the server:
Ethernet.begin(mac, ip);
server.begin();

// servo code
myservo.attach(3); // attaches the servo on pin 9 to the servo object
myservo.write(startPos);

// initialize the digital pin as an output.
// Pin 13 has an LED connected on most Arduino boards:
pinMode(13, OUTPUT);
}

void loop()
{
// listen for incoming clients
client = server.available();

if (client) {
// an http request ends with a blank line
boolean currentLineIsBlank = true;
while (client.connected()) {
if (client.available()) {
char c = client.read();
//Serial.print(c);

// if you’ve gotten to the end of the line (received a newline
// character) and the line is blank, the http request has ended,
// so you can send a reply
if (c == ‘\n’ && currentLineIsBlank) {
// send a standard http response header
client.println(“HTTP/1.1 200 OK”);
client.println(“Content-Type: text/html”);
client.println();

// output that we are raising the flag
client.println(“Zipwhip Sign Up Flag Going Up Degrees we will rotate to: ”);
raiseFlag();
client.println(“Done ”);
//delay(100);
//client.stop();

//raiseFlag();

break;
}
if (c == ‘\n’) {
// you’re starting a new line
currentLineIsBlank = true;
}
else if (c != ‘\r’) {
// you’ve gotten a character on the current line
currentLineIsBlank = false;
}
}
}
// give the web browser time to receive the data
delay(10);
// close the connection:
client.stop();
}
}

void raiseFlag() {

digitalWrite(13, HIGH); // set the LED on

myservo.attach(3); // attaches the servo on pin 9 to the servo object

// servo code
//myservo.attach(3); // attaches the servo on pin 9 to the servo object
//delay(100);
/* -10 (not possible on Sarvox Servo)
* 0
* 30
* 60
* 90 180
* 160
*/

// flag is all the way down. move it up. (may move to only 45 degrees down)
for(pos = startPos; pos>=30; pos-=1) // goes from 180 degrees to 0 degrees
{
client.print(pos);
client.print(” “);
//client.flush();
myservo.write(pos); // tell servo to go to position in variable ‘pos’
//delayMicroseconds(300);
delay(20); // waits 15ms for the servo to reach the position
}
client.println(“Done going forward. ”);

// Let’s pause by doing same positioning, but keep writing the same number
for(int ctr = 0; ctr < 60; ctr++)
{
myservo.write(pos);
delay(15);
}

// move flag all the way pointing down again
for(pos = 30; pos <= startPos; pos += 1) // goes from 0 degrees to 180 degrees
{ // in steps of 1 degree
client.print(pos);
client.print(” “);
//client.flush();
myservo.write(pos); // tell servo to go to position in variable ‘pos’
//delayMicroseconds(300);
delay(20); // waits 15ms for the servo to reach the position
}
client.println(“Done going backward. ”);
//myservo.detach();
delay(50);

myservo.detach(); // attaches the servo on pin 9 to the servo object

digitalWrite(13, LOW); // set the LED off

}

Filed under Tutorials Tagged with Arduino, Cloud Texting, coding, Savox Servo, Zipwhip

Tutorial: Using the Zipwhip API in Java to Popup Your Text Messages in a Bubble Window

July 17, 2011 Leave a comment

I wrote a couple of posts about sending and receiving text messages via the Zipwhip API. Those posts culminated in console output showing you the results of sending or receiving. In this post I’m going to take things further and actually have a slick looking bubble popup on your desktop showing you your text message as it comes in to the Zipwhip Cloud in real-time. The results will look something like below.

Watch the video below to check out how cool the bubble looks as it fades in and out.

We are going to create a new Eclipse project from scratch. Let’s call it ZipwhipBubble. Go into Eclipse and start a new project.

Call the project ZipwhipBubble.

The source tab can be left with the defaults.

On the Libraries tab make sure to add the 3 JARs that we used in the previous posts including Log4j, SLF4j, and of course the most important library—the Zipwhip API JAR. The easiest way to do this is to just download the zip file below of this entire project.

ZipwhipBubble.zip 1.1 MB

The contents of the zip file are as follows:

After having downloaded the above zip file, you can add the libraries from the JARs folder into the Libraries tab. Your tab should look like the screenshot below.

Click Finish. You should now have a new project like the window below.

You need to add your first class to the project.

Give the class the name “Main” and give it a package like “com.yourcompany.zw”. Of course set yourcompany to your company.

You will see a code window that’s mostly empty like below.

Now paste the following code into your window so you get a full class ready to go without you having to do any of the hard work because I did it all for you. You can also download the full Zip file of this project from the top of this posting that contains all of the JARs, source code, and images for the project.

Main.java 4.8 KB

package com.yourcompany.zw;

import org.apache.log4j.BasicConfigurator;
import org.apache.log4j.Level;
import org.apache.log4j.Logger;

import com.zipwhip.signals.dto.Message;
import com.zipwhip.api.DefaultZipwhipSubscriptionClient;
import com.zipwhip.api.HttpConnection;
import com.zipwhip.api.signals.JsonSocketSignalClient;
import com.zipwhip.signals.Signal;
import com.zipwhip.signals.SignalObserver;

public class Main {

    /**
 * @param args
 */
    public static void main(String[] args) {
        // Setup logging
        final Logger log = Logger.getLogger(Main.class);
        log.setLevel(Level.DEBUG);
        BasicConfigurator.configure();

        HttpConnection connection = new HttpConnection();
        connection.setDebug(true);

        String mobileNumber = "3135551234";
        String password = "mypassword";

        try {
            // This method will send a login request to the Zipwhip network and
            // if succcessful you will get a sesionKey set in your connection object
            // Watch out that you don't run "requestLogin()" too much because if you 
            // create more than 50 sessionKeys within 1 day you will no longer be able 
            // to get a key for 24 hours.
            connection.requestLogin(mobileNumber, password);
            //connection.setSessionKey("2ecfd63-4c57-4aa6-64a0-b0f120a1677a:1");
            connection.apiVersion = "/";
            log.info("Successfully authenticated. Your sessionKey is:" + connection.getSessionKey());

        } catch (Exception e) {
            log.fatal("Failed to authenticate and get sessionKey to Zipwhip network.");
            log.fatal(e);
            return;
        }

        DefaultZipwhipSubscriptionClient zipwhipSubscrClient;
        JsonSocketSignalClient signalClient;

        // This will create a new client object that allows you to perform
        // other tasks against the Zipwhip network once you have created 
        // an authenticated connection, i.e. have a sessionKey to communicate
        // to the Zipwhip network over.
        zipwhipSubscrClient = new DefaultZipwhipSubscriptionClient(connection);
        log.info("Just created our Default Client. Uses HTTP to connect to Zipwhip network.");

        // We will create our socket connection as well. You still need an HTTP connection because
        // the Zipwhip API uses HTTP calls to authenticate the socket connection.
        signalClient = new JsonSocketSignalClient(zipwhipSubscrClient);
        log.info("Just created our Socket always-connected client. Uses TCP/IP sockets to connect to Zipwhip network.");

        signalClient.addSignalObserver(new SignalObserver() {
            @Override
            public void notifySignalReceived(Signal signal) {
                log.debug("Signal received with uri " + signal.uri);

                switch (SignalUri.toSignalUri(signal.uri)) {
                case SIGNAL_MESSAGE_RECEIVE:
                    // We got a message. Let's show it.
                    // The Message object is contained in the signal.content object
                    // but you need to cast it.
                    Message msg = (Message)signal.content;
                    showIncomingMessageAlert(msg);
                    break;
                case SIGNAL_CONVERSATION_CHANGE:
                    // Do nothing for now
                    break;
                default:
                    // Do nothing if we don't know the signal
                    break;
                }
            }

            @Override
            public void notifySignalProviderEvent(boolean isConnected, String message, long frameCount) {
                log.debug("Reporting SignalProvider event: isConnected " + isConnected + ", message: " + message + ", frames: " + frameCount);
            }
        });

        signalClient.connect(connection.getSessionKey());

        log.info("Socket test will keep running on socket thread. Thanks for using Zipwhip.");
    }

    public static void showIncomingMessageAlert(Message message) {
        Bubble bubble = new Bubble(message.sourceAddress, message.body, "http://cloudtext.letsbobsled.com");
    }
}

enum SignalUri
{
    /*
 * /signal/message/progress
 * /signal/messageProgress/messageProgress
 * /signal/message/send
 * /signal/message/receive
 * /signal/message/read
 * /signal/message/delete
 * /signal/conversation/change
 */
    SIGNAL_MESSAGE_RECEIVE,
    SIGNAL_MESSAGE_PROGRESS,
    SIGNAL_MESSAGE_READ,
    SIGNAL_MESSAGE_DELETE,
    SIGNAL_MESSAGEPROGRESS_MESSAGEPROGRESS,
    SIGNAL_CONVERSATION_CHANGE,
    SIGNAL_CONTACT_NEW,
    SIGNAL_CONTACT_SAVE,
    SIGNAL_CONTACT_DELETE,
    NOVALUE;

    public static SignalUri toSignalUri(String str)
    {
        // We are going to use Java's valueOf method, so
        // we need to cleanup the URI string first
        // Get rid of first slash
        String str2 = str.substring(1, str.length());
        // convert slashes to underscores
        str2 = str2.replaceAll("/", "_");
        // go all upper case
        str2 = str2.toUpperCase();

        try {
            return valueOf(str2);
        }
        catch (Exception ex) {
            System.out.println("Found no match for SignalURI:" + str);
            return NOVALUE;
        }
    }
}

You will see that once you paste this code in you will have one error. You need to get the Bubble class that I created for this project.

The Bubble class takes care of all of the details of displaying a nice looking bubble on your desktop. All you have to do is create a bubble and pass it the mobile number, the text message, and a redirection URL to actually reply to the message. There are numerous web apps on the Internet that use the Zipwhip cloud so it is up to you to pick the URL that is appropriate.

Let’s go ahead and add our Bubble class to the project. Right click on the “com.yourcompany.zw” package name and choose New –> Class from the menu.

Call the class Bubble.

You will get a nice raw class like below.

Go ahead and paste in all of my hard work from my Bubble class. There’s a good deal of code in this class. The code is below. You can also download the file if you want. It’s below or it’s in the main Zip file linked to earlier in this posting.

Bubble.java 29.4 KB

package com.yourcompany.zw;

import java.awt.AlphaComposite;
import java.awt.BorderLayout;
import java.awt.Color;
import java.awt.Container;
import java.awt.Dimension;
import java.awt.Font;
import java.awt.GradientPaint;
import java.awt.Graphics;
import java.awt.Graphics2D;
import java.awt.GraphicsConfiguration;
import java.awt.Point;
import java.awt.Toolkit;
import java.awt.Transparency;
import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.awt.event.MouseListener;
import java.awt.event.MouseMotionAdapter;
import java.awt.event.MouseMotionListener;
import java.awt.geom.AffineTransform;
import java.awt.geom.Rectangle2D;
import java.awt.image.BufferedImage;
import java.io.File;
import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.URL;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.regex.Pattern;

import javax.imageio.ImageIO;
import javax.swing.ImageIcon;
import javax.swing.JButton;
import javax.swing.JComponent;
import javax.swing.JDialog;
import javax.swing.JFrame;
import javax.swing.JPanel;
import javax.swing.Timer;
import javax.swing.UIManager;
import javax.swing.text.AbstractDocument;

public class Bubble extends JDialog {

    // this code is static to manage the number of windows that are open
    protected static int numOpen;
    protected static int getOpen() { return numOpen; }
    protected static void windowOpen() { numOpen++; }
    protected static void windowClose() { numOpen--; }

    private int X=0;
    private int Y=0;
    private String fromMobileNumber;
    private String message;
    private String replyUrl;
    private boolean toFade = true;
    private float currOpacity;
    private Timer fadeInTimer;
    private Timer fadeOutTimer;

    javax.swing.JTextPane jTextPaneTxtMsg;
    AbstractDocument doc;

    public Bubble(String fromMobileNumber, String message, String replyUrl) {
        this(fromMobileNumber, message, replyUrl, true);
    }

    public Bubble(String fromMobileNumber, String message, String replyUrl, boolean toFade) {

        // initialize properties
        setFromMobileNumber(fromMobileNumber);
        setMessage(message);
        setReplyUrl(replyUrl);

        // initialize the UI of the bubble
        init();

        // set the location of where this bubble will be shown
        Dimension ourDim = Toolkit.getDefaultToolkit().getScreenSize();
        this.setLocation(
                (int)ourDim.getWidth() - this.getWidth() - 10,
                0 + ((this.getHeight() + -20) * getOpen()));

        // increment how many bubbles are open
        windowOpen();

        // ok, show it finally
        this.setVisible(true);
    }

    // Getters/setters
    public String getFromMobileNumber() {
        return StringUtil.format(fromMobileNumber, "(###) ###-####");
    }

    public void setFromMobileNumber(String fromMobileNumber) {
        this.fromMobileNumber = fromMobileNumber;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public String getReplyUrl() {
        return replyUrl;
    }

    public void setReplyUrl(String replyUrl) {
        this.replyUrl = replyUrl;
    }

    public boolean isToFade() {
        return toFade;
    }
    public void setToFade(boolean toFade) {
        this.toFade = toFade;
    }

    // Initialize the GUI
    public void init() {
        try {

            // When JFrame or JDialog
            this.setUndecorated(true);
            this.setModal(false);
            this.setFocusableWindowState(false);
            this.setAlwaysOnTop(true);

            try {
                UIManager.setLookAndFeel("com.sun.java.swing.plaf.windows.WindowsLookAndFeel");
            } catch (Exception evt) {}

            // Get bg image
            final BufferedImage backgroundImg = ImageIO.read(getClass().getResource("/resources/riser_shd.png"));

            // Set icon & title
            final BufferedImage z = ImageIO.read(getClass().getResource("/resources/z.png"));
            ((java.awt.Frame)this.getOwner()).setIconImage(z);
            this.setTitle(this.getFromMobileNumber() + ": " + this.getMessage());

            // Set layout
            this.setLayout(new BorderLayout());
            JPanel mainPanel = new JPanel(new BorderLayout()) {

                private static final long serialVersionUID = 1L;

                // The paintComponent override let's us make the entire
                // window transparent on the desktop so we get a cool effect
                @Override
                protected void paintComponent(Graphics g) {
                    Graphics2D g2d = (Graphics2D) g.create();

                    // code from
                    // http://weblogs.java.net/blog/campbell/archive/2006/07/java_2d_tricker.html
                    int width = backgroundImg.getWidth();
                    int height = backgroundImg.getHeight();
                    GraphicsConfiguration gc = g2d.getDeviceConfiguration();
                    BufferedImage img = gc.createCompatibleImage(
                        width,
                        height,
                        Transparency.TRANSLUCENT);
                    Graphics2D g2 = img.createGraphics();
                    g2.setComposite(AlphaComposite.Src);
                    g2.drawImage(backgroundImg, 0, 0, null);
                    g2.dispose();
                    g2d.drawImage(img, 0, 0, this);
                    g2d.dispose();
                }
            };

            // Setup the window
            final JDialog wnd = this;

            // This is the phone number and textarea message panel
            javax.swing.JPanel jPanelAll = new javax.swing.JPanel();
            javax.swing.JLabel jLabelMobileNum = new javax.swing.JLabel();
            this.jTextPaneTxtMsg = new javax.swing.JTextPane();
            JButton jButtonClose = new javax.swing.JButton();
            JButton jButtonReply = new javax.swing.JButton();

            jPanelAll.setOpaque(false);
            jPanelAll.setDoubleBuffered(false);
            jPanelAll.setName("jPanelAll"); // NOI18N

            jLabelMobileNum.setFont( new Font(null, Font.BOLD, 14));
            jLabelMobileNum.setForeground(new Color(67, 74, 84));
            jLabelMobileNum.setText(getFromMobileNumber());
            jLabelMobileNum.setName("jLabelMobileNum"); // NOI18N

            jTextPaneTxtMsg.setBorder(null);
            jTextPaneTxtMsg.setEditable(false);
            jTextPaneTxtMsg.setFont( new Font(null, Font.PLAIN, 12));
            jTextPaneTxtMsg.setOpaque(false);
            jTextPaneTxtMsg.setDoubleBuffered(false);
            jTextPaneTxtMsg.setText(getMessage());
            jTextPaneTxtMsg.setName("jTextPane1"); // NOI18N
            jTextPaneTxtMsg.setCaretPosition(0);

            javax.swing.JScrollPane jScrollPane1 = new javax.swing.JScrollPane(jTextPaneTxtMsg);
            jScrollPane1.getViewport().setOpaque(false);
            jScrollPane1.getViewport().setDoubleBuffered(false);

            jScrollPane1.setBorder(null);
            jScrollPane1.setHorizontalScrollBarPolicy(javax.swing.ScrollPaneConstants.HORIZONTAL_SCROLLBAR_NEVER);
            jScrollPane1.setVerticalScrollBarPolicy(javax.swing.ScrollPaneConstants.VERTICAL_SCROLLBAR_AS_NEEDED);
            jScrollPane1.setOpaque(false);
            jScrollPane1.setDoubleBuffered(false);
            jScrollPane1.setWheelScrollingEnabled(true);

            BufferedImage riserSpriteBtnImg = ImageIO.read(getClass().getResource("/resources/risergang.png"));

            // Define the close button
            jButtonClose.setIcon(new ImageIcon(riserSpriteBtnImg.getSubimage(1,1,14,14)));
            jButtonClose.setRolloverIcon(new ImageIcon(riserSpriteBtnImg.getSubimage(16,1,14,14)));
            jButtonClose.setPressedIcon(new ImageIcon(riserSpriteBtnImg.getSubimage(31,1,14,14)));
            jButtonClose.setBorder(null);
            jButtonClose.setBorderPainted(false);
            jButtonClose.setContentAreaFilled(false);
            jButtonClose.addActionListener(new ActionListener() {
                @Override
                public void actionPerformed(ActionEvent e) {
                    wnd.setVisible(false);
                }
            });

            // Define the reply button
            jButtonReply.setIcon(new ImageIcon(riserSpriteBtnImg.getSubimage(0,16,58,30)));
            jButtonReply.setRolloverIcon(new ImageIcon(riserSpriteBtnImg.getSubimage(0,47,58,30)));
            jButtonReply.setPressedIcon(new ImageIcon(riserSpriteBtnImg.getSubimage(0,78,58,30)));
            jButtonReply.setBorder(null);
            jButtonReply.setBorderPainted(false);
            jButtonReply.setContentAreaFilled(false);
            jButtonReply.addActionListener(new ActionListener() {
                @Override
                public void actionPerformed(ActionEvent e) {
                    openUri(getReplyUrl());
                    wnd.setVisible(false);
                }
            });

            // Do the layout positioning using horiz/vert groups 
            javax.swing.GroupLayout jPanel2Layout = new javax.swing.GroupLayout(jPanelAll);
            jPanelAll.setLayout(jPanel2Layout);

            jPanel2Layout.setHorizontalGroup(
                jPanel2Layout.createParallelGroup(javax.swing.GroupLayout.Alignment.LEADING)
                .addGroup(jPanel2Layout.createSequentialGroup()
                    .addGap(32)
                    .addGroup(jPanel2Layout.createParallelGroup(javax.swing.GroupLayout.Alignment.LEADING)
                        .addComponent(jLabelMobileNum)
                        .addComponent(jScrollPane1, javax.swing.GroupLayout.PREFERRED_SIZE, 150, javax.swing.GroupLayout.PREFERRED_SIZE)
                    )
                    .addContainerGap(73, Short.MAX_VALUE))
                .addGroup(jPanel2Layout.createParallelGroup(javax.swing.GroupLayout.Alignment.LEADING)
                    .addGroup(jPanel2Layout.createSequentialGroup()
                        .addGap(169)
                        .addComponent(jButtonClose, javax.swing.GroupLayout.PREFERRED_SIZE, 14, javax.swing.GroupLayout.PREFERRED_SIZE)
                        .addContainerGap(261, Short.MAX_VALUE)))
                .addGroup(jPanel2Layout.createParallelGroup(javax.swing.GroupLayout.Alignment.LEADING)
                    .addGroup(jPanel2Layout.createSequentialGroup()
                        .addGap(128)
                        .addComponent(jButtonReply, javax.swing.GroupLayout.PREFERRED_SIZE, 58, javax.swing.GroupLayout.PREFERRED_SIZE)
                        .addContainerGap(251, Short.MAX_VALUE)))
            );

            jPanel2Layout.setVerticalGroup(
                jPanel2Layout.createParallelGroup(javax.swing.GroupLayout.Alignment.LEADING)
                .addGroup(jPanel2Layout.createSequentialGroup()
                    .addGap(32)
                    .addComponent(jLabelMobileNum)
                    .addPreferredGap(javax.swing.LayoutStyle.ComponentPlacement.RELATED)
                    .addComponent(false, jScrollPane1, javax.swing.GroupLayout.DEFAULT_SIZE, 100, javax.swing.GroupLayout.PREFERRED_SIZE)
                    .addContainerGap(64, Short.MAX_VALUE))
                .addGroup(jPanel2Layout.createParallelGroup(javax.swing.GroupLayout.Alignment.LEADING)
                    .addGroup(jPanel2Layout.createSequentialGroup()
                        .addGap(28)
                        .addComponent(jButtonClose, javax.swing.GroupLayout.PREFERRED_SIZE, 14, javax.swing.GroupLayout.PREFERRED_SIZE)
                        .addContainerGap(300, Short.MAX_VALUE)))
                .addGroup(jPanel2Layout.createParallelGroup(javax.swing.GroupLayout.Alignment.LEADING)
                    .addGroup(jPanel2Layout.createSequentialGroup()
                        .addGap(168)
                        .addComponent(jButtonReply, javax.swing.GroupLayout.PREFERRED_SIZE, 30, javax.swing.GroupLayout.PREFERRED_SIZE)
                        .addContainerGap(146, Short.MAX_VALUE)))
            );

            // End phone/message panel

            // Setup final main paenl
            mainPanel.add(jPanelAll, BorderLayout.WEST);
            mainPanel.setDoubleBuffered(false);
            mainPanel.setOpaque(true);
            this.add(mainPanel, BorderLayout.CENTER);

            this.setAlwaysOnTop(true);
            this.setSize(216, 234);
            this.setLocationRelativeTo(null);
            com.sun.awt.AWTUtilities.setWindowOpaque(this, false);

            // Watch mouse movements and clicks to allow dragging of window
            addMouseListener(new MouseAdapter()
            {
                public void mousePressed(MouseEvent e)
                {
                    // Check for double-click
                    if (e.getClickCount() >= 2) {
                        // Open the website to let them reply
                        openUri(getReplyUrl());
                        setVisible(false);
                    } else {
                        // Do drag operation
                        X=e.getX();
                        Y=e.getY();
                    }
                }

            });

            addMouseMotionListener(new MouseMotionAdapter()
            {
                public void mouseDragged(MouseEvent e)
                {
                    setLocation(getLocation().x+(e.getX()-X),getLocation().y+(e.getY()-Y));
                }
            });

        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    @Override
    public void setVisible(boolean b) {

        // Handle fading in or fading out

        // If setvisible is true
        if (b) {

            // See if we need to fade in
            if (this.toFade) {
                // mark the popup with 0% opacity
                this.currOpacity = 0;
                com.sun.awt.AWTUtilities.setWindowOpacity(this, 0.0f);
            }

            super.setVisible(b);

            final JDialog popupWindow = this;

            if (this.toFade) {
                // start fading in
                this.fadeInTimer = new Timer(50, new ActionListener() {
                    public void actionPerformed(ActionEvent e) {
                        currOpacity += 10;
                        if (currOpacity <= 100) {
                            com.sun.awt.AWTUtilities.setWindowOpacity(popupWindow,
                                    currOpacity / 100.0f);
                            // workaround bug 6670649 - should call
                            // popupWindow.repaint() but that will not repaint the
                            // panel
                            popupWindow.getContentPane().repaint();
                        } else {
                            currOpacity = 100;
                            fadeInTimer.stop();
                        }
                    }
                });
                this.fadeInTimer.setRepeats(true);
                this.fadeInTimer.start();
            }

        } else {

            // If setvisible is false

            // Handle fading out, if they want a fade
            if (this.toFade) {

                // cancel fade-in if it's running.
                if (this.fadeInTimer.isRunning())
                    this.fadeInTimer.stop();

                final Bubble popupWindow = this;

                // start fading out
                this.fadeOutTimer = new Timer(50, new ActionListener() {
                    public void actionPerformed(ActionEvent e) {
                        currOpacity -= 10;
                        if (currOpacity >= 0) {
                            com.sun.awt.AWTUtilities.setWindowOpacity(popupWindow,
                                    currOpacity / 100.0f);
                            // workaround bug 6670649 - should call
                            // popupWindow.repaint() but that will not repaint the
                            // panel
                            popupWindow.getContentPane().repaint();
                        } else {
                            fadeOutTimer.stop();
                            popupWindow.setToFade(false);
                            popupWindow.setVisible(false);
                            currOpacity = 0;
                        }
                    }
                });
                this.fadeOutTimer.setRepeats(true);
                this.fadeOutTimer.start();

            } else {

                // setVisible is being set to false and we're not in fadeout mode,
                // so let's let the super handle
                // it cuz we don't want to interfere if there's no fading going on
                windowClose();
                super.setVisible(false);
                this.removeAll();
                this.dispose();

            }
        }
    }

    public void openUri(String url) {

        if( !java.awt.Desktop.isDesktopSupported() ) {

            System.err.println( "Desktop is not supported (fatal)" );
            return;
        }

        java.awt.Desktop desktop = java.awt.Desktop.getDesktop();

        if( !desktop.isSupported( java.awt.Desktop.Action.BROWSE ) ) {

            System.err.println( "Desktop doesn't support the browse action (fatal)" );
            return;
        }

        try {

            java.net.URI uri = new java.net.URI( url );
            desktop.browse( uri );
        }
        catch ( Exception e ) {

            System.err.println( e.getMessage() );
        }

    }

}

class MoveMouseListener implements MouseListener, MouseMotionListener {
    JComponent target;
    Point start_drag;
    Point start_loc;

    public MoveMouseListener(JComponent target) {
        this.target = target;
    }

    public static JFrame getFrame(Container target) {
        if (target instanceof JFrame) {
            return (JFrame) target;
        }
        return getFrame(target.getParent());
    }

    Point getScreenLocation(MouseEvent e) {
        Point cursor = e.getPoint();
        Point target_location = this.target.getLocationOnScreen();
        return new Point((int) (target_location.getX() + cursor.getX()),
                (int) (target_location.getY() + cursor.getY()));
    }

    public void mouseClicked(MouseEvent e) {
    }

    public void mouseEntered(MouseEvent e) {
    }

    public void mouseExited(MouseEvent e) {
    }

    public void mousePressed(MouseEvent e) {
        this.start_drag = this.getScreenLocation(e);
        this.start_loc = this.getFrame(this.target).getLocation();
    }

    public void mouseReleased(MouseEvent e) {
    }

    public void mouseDragged(MouseEvent e) {
        Point current = this.getScreenLocation(e);
        Point offset = new Point((int) current.getX() - (int) start_drag.getX(),
                (int) current.getY() - (int) start_drag.getY());
        JFrame frame = this.getFrame(target);
        Point new_location = new Point(
                (int) (this.start_loc.getX() + offset.getX()), (int) (this.start_loc
                        .getY() + offset.getY()));
        frame.setLocation(new_location);
    }

    public void mouseMoved(MouseEvent e) {
    }
}

class StringUtil {

    //private static final Logger logger = LoggerFactory.getLogger(StringUtil.class);

    public static final String EMPTY_STRING = "";
    public static final int MAX_MOBILE_NUMBER_DIGITS = 16; // Finland being the longest we could find 99500-1-202-444-1212, plus a buffer...
    public static final List<Character> VALID_NUMBERS;
    public static final List<Character> VALID_SPECIAL_CHARACTERS;

    static {
        VALID_NUMBERS = Arrays.asList(new Character[] { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9' });
        VALID_SPECIAL_CHARACTERS = Arrays.asList(new Character[]{'!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '`', '[', ']', '\\', '{', '}', '|', '<', '>', '?', ',', '.', '/', ':', ';', '\'', '"', '+', '~', '*', '.'});
    }

    /**
 * Strips all characters that are not numbers (0 - 9) and returns a new
 * string. Returns and empty string if the mobile number is null or empty.
 * 
 * @param mobileNumber - mobile number string to parse
 * @return String - parsed mobile number
 */
    public static String safeCleanMobileNumber(String mobileNumber) {

        //logger.debug("getting clean for " + mobileNumber);

        if (isNullOrEmpty(mobileNumber)) {
            //logger.debug("was nullOrEmpty ");
            return null;
        }

        StringBuilder cleanMobileNumber = new StringBuilder();
        for (int i = 0; i < mobileNumber.length(); i++) {
            if (VALID_NUMBERS.contains(mobileNumber.charAt(i))) {
                cleanMobileNumber.append(mobileNumber.charAt(i));
            }
        }

        // remove the first (1) at the beginning of the to match default us
        // numbers
        // 10 digits
        if (cleanMobileNumber.length() > 10 && startsWith(cleanMobileNumber.toString(), "1")) {
            //logger.debug("clean 1 " + cleanMobileNumber.substring(1));
            return cleanMobileNumber.substring(1);
        }
        if (cleanMobileNumber.length() > 10 && startsWith(cleanMobileNumber.toString(), "+1")) {
            //logger.debug("clean 2 " + cleanMobileNumber.substring(1));
            return cleanMobileNumber.substring(2);
        }

        //logger.debug("clean " + cleanMobileNumber.toString());
        return cleanMobileNumber.toString();
    }

    /**
 * Same as safeCleanMobileNumber except for devices
 * in which case the device number is removed first
 *
 * @param mobileNumber - mobile number string to parse
 * @return String - parsed mobile number
 */
    public static String safeCleanMobileNumberRemoveDevice(String mobileNumber) {

        if (startsWith(mobileNumber, "device:/")) {

            int index = mobileNumber.lastIndexOf('/');

            // If the last index of '/' is > than the first
            if (index > 7) {
                mobileNumber = mobileNumber.substring(0, index);
            }
        }

        return safeCleanMobileNumber(mobileNumber);
    }

    public static boolean isValidEmail(String email){
        // see http://www.mkyong.com/regular-expressions/how-to-validate-email-address-with-regular-expression/
        Pattern pattern ;
        java.util.regex.Matcher matcher;
        final String EMAIL_PATTERN = "^[\\w\\-]+(\\.[\\w\\-]+)*@([A-Za-z0-9-]+\\.)+[A-Za-z]{2,4}$";

        pattern = Pattern.compile(EMAIL_PATTERN);
        matcher = pattern.matcher(email);

        return matcher.matches();
    }


    /**
 * The length is valid if it is between 3 and 6 or over
 * 10 and up to and including 20
 * 3-6 length means short codes
 * 10 length 000-000-0000
 * 10+ means international
 *
 * @param mobileNumber
 * @return
 */
    public static boolean isValidLengthMobileNumber(String mobileNumber) {

        if (isNullOrEmpty(mobileNumber))  {
            return false;
        }

        int numberLength = mobileNumber.length();

        // Wrong if under 3 and between 7 and 9 digits long or longer than 20
        if (numberLength < 3 || numberLength == 7 || numberLength == 8 || numberLength == 9 || numberLength > MAX_MOBILE_NUMBER_DIGITS) {
            return false;
        }
        // Correct is 3 to 6 for short codes and 10 to 20 for long international
        // numbers, including a buffer
        return true;
    }

    public static boolean startsWith(String string1, String toFind) {
        if (string1 == null && toFind == null){
            // null contains null.
            return true;
        } else if (string1 == null){
            return false;
        }

        if (StringUtil.equalsIgnoreCase(string1, toFind)){
            return true;
        }

        return string1.toLowerCase().startsWith(toFind.toLowerCase());
    }

    public static boolean endsWith(String source, String toFind) {
        if (source == null) {
            return false;
        }

        return source.endsWith(toFind);
    }

    public static String defaultValue(String string, String defaultValue) {
        if (StringUtil.isNullOrEmpty(string)){
            return defaultValue;
        }
        return string;
    }

    public static final class Schema {

        public static final String TEL = "tel";
    }

    /**
 * Takes a string representing the display name and returns and array with
 * first name and last name.
 * 
 * Returns null if null or empty input
 * 
 * @param displayName
 * @return String[]
 */
    public static String[] splitDisplayName(String displayName) {
        if (displayName == null || displayName.length() < 1) {
            return null;
        }

        String[] names = displayName.split(" ");

        return names;
    }

    /**
 * Takes a string representing a list of mobile numbers as
 * 5555551212, 5556667878 or
 * 5555551212; 5556667878
 *
 * Returns null if null or empty input
 *
 * @param sourceNumber
 * @return List<String>
 */
    public static List<String> splitMobileNumbers(String sourceNumber) {

        ArrayList<String> result = new ArrayList<String>();
        int last = 0;

        for (int i = 0; i < sourceNumber.length(); i++) {
            if (sourceNumber.charAt(i) == ';' || sourceNumber.charAt(i) == ',') {
                String number = sourceNumber.substring(last, i).trim();
                result.add(number);
                last = i + 1;
            }
        }
        result.add(sourceNumber.substring(last).trim());
        return result;
    }

    /**
 * Format the mobile number
 * 
 * @param mobileNumber
 * @param format
 * - ###-###-####
 * @return
 */
    public static String format(String mobileNumber, String format) {
        if (mobileNumber == null || mobileNumber.length() < 1 || format == null || format.length() < 1) {
            return mobileNumber;
        }

        int numberCount = 0;
        for (int i = 0; i < format.length(); i++) {
            if (format.charAt(i) == '#') {
                numberCount++;
            }
        }
        String number = safeCleanMobileNumber(mobileNumber);
        if (numberCount != number.length()) {
            return mobileNumber;
        }

        List<Character> numberChars = new ArrayList<Character>();
        char[] chars = new char[format.length()];
        int count = 0;
        for (int i = 0; i < format.length(); i++) {
            if (format.charAt(i) == '#') {
                numberChars.add(number.charAt(count));
                chars[i] = number.charAt(count);
                count++;
            } else {
                numberChars.add(format.charAt(i));
                chars[i] = format.charAt(i);
            }
        }

        return new String(chars);
    }

    public static String stringArrayToDelimittedString(String[] arrayString, String delimiter) {
        return stringArrayToDelimittedString(arrayString, delimiter, null);
    }

    public static String stringArrayToDelimittedString(String[] arrayString, String delimiter, String format) {

        if (arrayString == null || delimiter == null) {
            return null;
        }

        StringBuilder delimittedString = new StringBuilder();
        if (format == null || format.length() < 1) {
            for (String number : arrayString) {
                delimittedString.append(number).append(delimiter);
            }
        } else {
            for (String number : arrayString) {
                number = StringUtil.format(number, format);
                delimittedString.append(number).append(delimiter);
            }
        }

        return delimittedString.toString();
    }

    /**
 * Takes a delimited values string and returns is as a set
 * 
 * @param string
 * @param delimiter
 * @return Set<String>
 */
    public static Set<String> stringToSet(String string, String delimiter) {
        if (isNullOrEmpty(string) || isNullOrEmpty(delimiter)) {
            return null;
        }

        String[] toArray = string.split(delimiter);
        Set<String> toSet = null;
        if (toArray != null && toArray.length > 0) {
            toSet = new HashSet<String>();
            for (String value : toArray) {
                if (!isNullOrEmpty(value)) toSet.add(value);
            }
        }
        return toSet;
    }

    /**
 * Return true if the string is null. Trims the string and checks if it is
 * an empty string
 * 
 * @param string
 * @return
 */
    public static boolean isNullOrEmpty(String string) {
        return (string == null || string.trim().length() < 1);
    }

    public static boolean isNullOrEmpty(String... strings) {
        for (String string : strings) {
            if (isNullOrEmpty(string)) {
                return true;
            }
        }
        return false;
    }

    public static boolean exists(String string) {
        return !isNullOrEmpty(string);
    }

    public static boolean equals(String string1, String string2){
        if (string1 == string2)
            return true; // covers both null, or both same instance
        if (string1 == null){
            return false; // covers 1 null, other not.
        }

        return (string1.equals(string2)); // covers equals
    }

    public static boolean equalsIgnoreCase(String string, String type) {
        boolean oneEmpty = isNullOrEmpty(string);
        boolean otherEmpty = isNullOrEmpty(type);
        if (oneEmpty && otherEmpty) {
            return true;
        }
        if (oneEmpty || otherEmpty) {
            return false;
        }

        return string.equalsIgnoreCase(type);
    }

    public static boolean isIntegerParsable(String toCheck){
        if (toCheck == null) return false;
        try {
            Integer.parseInt(toCheck);
            return true;
        } catch (NumberFormatException e){
            return false;
        }
    }

    public static boolean isLongParsable(String toCheck){
        if (toCheck == null) return false;
        try {
            Long.parseLong(toCheck);
            return true;
        } catch (NumberFormatException e){
            return false;
        }
    }

    public static String[] convert(Object... parameters){
        String[] args = new String[parameters.length];

        int idx = 0;
        for(Object object : parameters){
            args[idx] = String.valueOf(object);
            idx ++;
        }

        return args;
    }

    public static String join(Object... parts) {
        StringBuilder sb = new StringBuilder();
        for(Object part : parts){
            if (part == null){
                continue;
            }
            sb.append(String.valueOf(part));
        }
        return sb.toString();
    }

    /**
 * Check if the last character in the string matches the input character and
 * removes. If the match fails, we return the string as it is.
 * 
 * @param inputString
 * @param c
 * @return string
 */
    public static String removeLast(String inputString, char c) {

        if (isNullOrEmpty(inputString)) {
            return inputString;
        }

        if (inputString.charAt(inputString.length() - 1) == c) {
            return inputString.substring(0, inputString.length() - 1);
        }

        return inputString;
    }

    public static String stripStringNull(String param) {
        return (StringUtil.isNullOrEmpty(param) || "null".equalsIgnoreCase(param)) ? StringUtil.EMPTY_STRING : param;
    }

    /**
 * 
 * @param contents
 * @param key
 * @param value
 * @return
 */
    public static String convertPatterns(String contents, Map<String, String> keyVals) {

        if (contents == null) {
            throw new NullPointerException("Cannot convert null pattern");
        }

        for(Map.Entry<String, String> entry : keyVals.entrySet()) {
            contents = contents.replaceAll(entry.getKey(), entry.getValue());
        }

        return contents;
    }

    public static String convertPatterns(
        final String contents,
        final String hostnamePattern,
        final String string
    ) {

        final Map<String, String> keyVals = new HashMap<String, String>();

        return convertPatterns(contents, keyVals);

    }

}

Your Eclipse window package explorer should have two files in it now: Bubble.java and Main.java.

Now, you can go ahead and run your code but you will get errors because you don’t have the pictures required by the Bubble.java class to render out the nice looking bubble. So, you need to go create a resources folder and place the pictures inside it.

Then paste in the 3 pictures into the folder. These pictures are also in the main zip file for the entire project at the start of this posting. Or you can download them here.

resources.zip 23 KB

Ok, now go to your Main.java file and run the program. The best way to do this is to move your cursor into the static void main() method and right-click. Choose Run As –> Java Application. This will execute the static void main() and actually run your app. You will see a lot of output in the console window. This is the Zipwhip API giving you lots of debugging feedback.

Now, here’s the big moment. Go ahead and send yourself a text message to the phone you are logged in as. You will get a slick popup window fading in on your desktop in the upper right corner. You can double-click the bubble to jump to the configured URL to reply to your message. You can also hit the reply button or close the bubble.

The key extra chunk of code for this example vs. the previous posting is that we are now listening to signals and parsing them so we can perform a switch. I created an ENUM of some of the standard signals from the Zipwhip API so that I could perform a switch since Java still does not let you do a switch on strings.

Here is the signal observer code and the switch statement.

 1: signalClient.addSignalObserver(new SignalObserver() {

 2:     @Override

 3:     public void notifySignalReceived(Signal signal) {

 4:         log.debug("Signal received with uri " + signal.uri);

5:

 6:         switch (SignalUri.toSignalUri(signal.uri)) {

 7:         case SIGNAL_MESSAGE_RECEIVE:

 8:             // We got a message. Let's show it.

 9:             // The Message object is contained in the signal.content object

 10:             // but you need to cast it.

 11:             Message msg = (Message)signal.content;

 12:             showIncomingMessageAlert(msg);

 13:             break;

 14:         case SIGNAL_CONVERSATION_CHANGE:

 15:             // Do nothing for now

 16:             break;

 17:         default:

 18:             // Do nothing if we don't know the signal

 19:             break;

 20:         }

 21:     }

22:

 23:  });

You will need to also have the class for the Enum. I got lazy and just placed it into the Main.java file. Technically you should likely place this in its own class file.

 1: enum SignalUri

 2: {

 3:     /*

 4:  * /signal/message/progress

 5:  * /signal/messageProgress/messageProgress

 6:  * /signal/message/send

 7:  * /signal/message/receive

 8:  * /signal/message/read

 9:  * /signal/message/delete

 10:  * /signal/conversation/change

 11:  */

 12:     SIGNAL_MESSAGE_RECEIVE,

 13:     SIGNAL_MESSAGE_PROGRESS,

 14:     SIGNAL_MESSAGE_READ,

 15:     SIGNAL_MESSAGE_DELETE,

 16:     SIGNAL_MESSAGEPROGRESS_MESSAGEPROGRESS,

 17:     SIGNAL_CONVERSATION_CHANGE,

 18:     SIGNAL_CONTACT_NEW,

 19:     SIGNAL_CONTACT_SAVE,

 20:     SIGNAL_CONTACT_DELETE,

 21:     NOVALUE;

22:

 23:     public static SignalUri toSignalUri(String str)

 24:     {

 25:         // We are going to use Java's valueOf method, so

 26:         // we need to cleanup the URI string first

 27:         // Get rid of first slash

 28:         String str2 = str.substring(1, str.length());

 29:         // convert slashes to underscores

 30:         str2 = str2.replaceAll("/", "_");

 31:         // go all upper case

 32:         str2 = str2.toUpperCase();

33:

 34:         try {

 35:             return valueOf(str2);

 36:         }

 37:         catch (Exception ex) {

 38:             System.out.println("Found no match for SignalURI:" + str);

 39:             return NOVALUE;

 40:         }

 41:     }

 42: }

This posting is about the Zipwhip API so I don’t want to get into the details of the cool looking bubble being generated from the Bubble() class, but it’s worth noting that we are using some of the features only available in later versions of Java that let you create transparent windows. We are doing some fade in/out tricks. We are manually adding mouse listeners to let you drag the window around. We are doing some sprite tricks with getSubImage() so we can repurpose some web PNGs as well. It was quite a lot of work to get that Bubble class setup, but it was well worth it because you can run this app non-stop and actually start using it to get real-time popups.

If you want to try some tricks with the Bubble to see if there are things you like better than the settings I picked, one of the things I recommend is to allow the window focus to be set. If you do this, you will be able to select the text from the message to copy it to the clipboard. Go into the code and change the this.setFocusableWindowState() line:

Notice that you can now select text, hit Ctrl-C to copy it to the clipboard, hit tab to choose Reply, hit the spacebar to choose the button, etc. The reason I didn’t pick allowing focus is that if a bubble pops in while you’re doing something like writing an email, I don’t think it’s a good idea to steal the focus. The user could consider that rude. However, it’s up to you how you want to setup your app.

Ok, thanks for reading the tutorial. Enjoy playing with your popup bubbles on your desktop when your friends text you on your phone.

Filed under Tutorials Tagged with code, pop up windows, text messaging, Zipwhip API

Tutorial: Using the Zipwhip API in Java to Receive Text Messages via Sockets

July 3, 2011 3 Comments

I wrote a post about two weeks ago about using the Zipwhip API in Java to send a text message. This post will complete the picture by showing you how to receive a text message via the Zipwhip API. This is a little bit more involved than the previous post. Sending a message simply requires your code to zip off a message via the API which uses HTTP. Receiving, however, requires your code to bind to Zipwhip’s socket server and stay bound in to wait for the moment a text message actually arrives. This means your app must always be running to receive the text message.

As a background, there are a few ways to receive text messages from the Zipwhip network:

Short polling
You can query Zipwhip’s session/update API once every 10 seconds, or however often, and you will be told what signals you missed such as new messages, messages being marked as read, new contacts, etc. This means you are not getting messages in real-time, however this is a super simplistic method of getting updates or events. This is especially useful in Javascript apps that can’t create sockets.
IP Socket-based push
You can bind into a socket and get real-time signals from the Zipwhip network. This means that when a text message hits your phone, it will be immediately (within milliseconds) hitting your app. This requires a bit more complexity in your app, but it’s very worthwhile for the best experience.
Post to a URL
This method allows you to tell the Zipwhip network to post a copy of all of your signals to a URL. This is a very cool feature that Zipwhip gives you, but you must be running your own server at a public address for Zipwhip to be able to reach it. If you have to move your server around, you have to unregister the URL and reregister the URL you want posted to. This solution would not likely be used by consumer apps due to the configuration overhead.

This tutorial will just describe how to do IP Socket-based push because, in my opinion, it’s one of the coolest aspects of the Zipwhip network and the most powerful for the consumer or general developer. It lets you connect from any location at any time, or as many locations as you want, and get all of your signals delivered. So, if I want to run an app on my laptop, my desktop, my tablet, my Ubuntu box, and my Google TV, to get my text messages I can simply bind in via a socket and get copies of texts popping up everywhere I could ever want them. Because the Zipwhip network propagates things such as text messages being marked as read, especially back to my phone, I don’t have to mark a text as read on all of my computers like the way Skype makes me mark messages as read everywhere or the way Outlook makes me expire my envelope in the system tray on all of my machines.

Let’s get started. We need to fire up Eclipse where we’ll make a new Java project from scratch.

Call the project ZipwhipAPISocketExample. (BTW, you can zoom in on the screenshots by clicking them.)

Go to the Libraries tab and make sure you have the ZipwhipAPI Jar added as well as the Log4j Jar. You can get these in your list by clicking on “Add External JARs…”. You will need to download the ZipwhipAPI from here if you don’t already have it. If you don’t have Log4j you can search for it or head over to the Apache Log4j project here. You will also need slf4j which is a small utility that abstracts Log4j to be used in different environments. These log dependencies are just a result of the ZipwhipAPI relying on them. They’re nice to use in your own projects too if you want to.

Zipwhip API Jar (820KB)

If you want to also download the dependencies you can grab the files below. Because these are popular files, you may already have these.

Log4j Jar (ZipwhipAPI.jar depends on this Jar)

Slf4j Jar (ZipwhipAPI.jar depends on this Jar)

Hit Finish on the dialog above. You should now have a new project called “ZipwhipAPISocketExample” and a clean Eclipse window with an empty project.

Create a new Java class so that we have a file to create our entry point in.

Create a package name like com.yourcompany.zwsocket. Of course swap in your name or your company’s name in place of what I typed. Then call the Java class ExampleMain or whatever name you prefer. Make sure to check off to create the “void main()” method so we have an entry point to our example.

Click Finish. You should see a new Java class in your editor.

Now, replace all of the text with the source code below. You can download it here, or you can cut & paste it.

ExampleMain.java

package com.yourcompany.zwsocket;

import com.zipwhip.api.DefaultZipwhipSubscriptionClient;
import com.zipwhip.api.HttpConnection;
import com.zipwhip.api.signals.JsonSocketSignalClient;
import com.zipwhip.signals.Signal;
import com.zipwhip.signals.SignalObserver;

public class ExampleMain {

    public static void main(String[] args) {

        // Create our connection object for the Zipwhip API.
        // This object gets an authenticated HTTP connection to the 
        // Zipwhip network via a login which gets you a sessionKey.
        HttpConnection connection = new HttpConnection();

        String mobileNumber = "3135551234";
        String password = "mypassword";

        System.out.println(String.format(
            "Logging into Zipwhip network with mobile:%s, pass:%s",
            mobileNumber, password));

        try {
            // This method will send a login request to the Zipwhip network and
            // if successful you will get a sesionKey set in your connection object
            // Watch out that you don't run "requestLogin()" too much because if you 
            // create more than 50 sessionKeys within 1 day you will no longer be able 
            // to get a key for 24 hours.
            connection.requestLogin(mobileNumber, password);
            // You can alternately just set your sessionKey from the last time you
            // did a requestLogin(). Just store the sessionKey and use that. It
            // is good for 30 days. Uncomment the line below and set your sessionKey.
            // connection.setSessionKey("2e08a863-4c57-7af6-92c0-b0a120a16778:32423");

            System.out.println("Got sessionKey:" + connection.getSessionKey());

            // Set the version to "/" so we use non-signed web service calls
            connection.apiVersion = "/";

        } catch (Exception e) {
            System.out.println("Failed to authenticate and get sessionKey to Zipwhip network.");
            return;
        }

        // Zipwhip's HTTP web services client library. It uses the connection object for
        // an authenticated transport.
        DefaultZipwhipSubscriptionClient zipwhipSubscrClient;

        // Zipwhip's Socket client.
        JsonSocketSignalClient signalClient;

        // This will create a high level client object that allows you to perform
        // the full suite of tasks against the Zipwhip network such as send texts,
        // create contacts, create groups, etc.
        zipwhipSubscrClient = new DefaultZipwhipSubscriptionClient(connection);

        // We will create our TCP/IP socket connection as well. You still need an 
        // HTTP client because the Zipwhip API uses HTTP calls in concert with the 
        // socket because the socket only pushes signals to you. If you want to
        // send in a command, you do it over the DefaultZipwhipSubscriptionClient 
        // HTTP client.
        signalClient = new JsonSocketSignalClient(zipwhipSubscrClient);

        // We need to add our callback methods to the socket client so that
        // we can act upon incoming signals.
        signalClient.addSignalObserver(new SignalObserver() {

            // This method is called when a push socket signal is received
            @Override
            public void notifySignalReceived(Signal signal) {
                //log.debug("Signal received with uri " + signal.uri);
                System.out.println("Signal received with uri " + signal.uri);
                System.out.println("\t" + signal.rawContent);
            }

            @Override
            public void notifySignalProviderEvent(boolean isConnected, String message, long frameCount) {
                System.out.println("Socket status. isConnected:" + isConnected +
                    ", msg:" + message + ", frame:" + frameCount);
            }
        });

        // Let's finally call the connect method to actually bind in over TCP/IP
        signalClient.connect(connection.getSessionKey());

        System.out.println("Done with socket test void main(), however socket thread will keep running listening for signals until you kill the process. Thanks for using Zipwhip.");

    }

}

After you get the source code into Eclipse, your window should look like below. Remember, you can zoom by clicking the image.

You need to set your mobile number and password before you can run the file. If you don’t have a login to the Zipwhip network, you can get one via your carrier if your carrier is a Zipwhip partner.

Go ahead and run the code. Just right-click anywhere in the code and choose Run As –> Java Application.

When the code runs, you should see output in the Console.

The output in the Console window will be similar to the text below. Don’t worry, I changed the phone numbers and other important details in the output like the sessionKey because those are sensitive items of data.

Logging into Zipwhip network with mobile:3134447002, pass:****
log4j:WARN No appenders could be found for logger (com.zipwhip.api.HttpConnection).
log4j:WARN Please initialize the log4j system properly.
Got sessionKey:64abcd3d-9ab6-45ed-aa78-91e4a262169:1
Done with socket test void main(), however socket thread will keep running listening for signals until you kill the process. Thanks for using Zipwhip.
Socket status. isConnected:false, msg:Connecting..., frame:0
Socket status. isConnected:true, msg:Connection Established - Negotiating, frame:0
Socket status. isConnected:true, msg:Connection Established, frame:1
Socket status. isConnected:true, msg:Connection Established, frame:1
Socket status. isConnected:true, msg:Connection Established, frame:2
Socket status. isConnected:true, msg:Connection Established, frame:3
Signal received with uri /signal/message/receive
    {"id":"11218401","content":{"to":"","body":"hey, what's up duder?","bodySize":21,"visible":true,"transmissionState":{"enumType":"com.zipwhip.outgoing.TransmissionState","name":"QUEUED"},"type":"MO","metaDataId":0,"dtoParentId":1,"scheduledDate":null,"thread":"","carrier":"Tmo","deviceId":1,"openMarketMessageId":"","lastName":"Phone","class":"com.zipwhip.website.data.dto.Message","isParent":false,"lastUpdated":"2011-07-03T22:49:17-07:00","loc":"","messageConsoleLog":"Message created on Sun Jul 03 22:49:17 PDT 2011. Setting status code to 4 by default","deleted":false,"contactId":2782629,"uuid":"7e397eb-01ca-4f19-9166-b8d431c52cf","isInFinalState":false,"statusDesc":"","cc":"","subject":"","encoded":true,"expectDeliveryReceipt":false,"transferedToCarrierReceipt":null,"version":1,"statusCode":4,"id":118401,"fingerprint":"29091579","parentId":0,"phoneKey":"samSGH-T729","smartForwarded":false,"fromName":null,"isSelf":false,"firstName":"Sidekick","sourceAddress":"2063984565","deliveryReceipt":null,"dishedToOpenMarket":null,"errorState":false,"creatorId":0,"advertisement":null,"bcc":"","fwd":"","contactDeviceId":1,"smartForwardingCandidate":false,"destAddress":"3134447333","DCSId":"not parsed at the moment","latlong":"","new":false,"address":"ptn:/2063982344","dateCreated":"2011-07-03T22:49:27-07:00","UDH":"","carbonedMessageId":-1,"channel":" ","isRead":false},"scope":"device","reason":null,"tag":null,"event":"receive","class":"com.zipwhip.signals.Signal","uuid":"787cfec2-d094-4e6d-9b59-d8f55486d","type":"message","uri":"/signal/message/receive"}
Socket status. isConnected:true, msg:Connection Established, frame:4
Signal received with uri /signal/conversation/change
    {"id":"8312","content":{"lastContactFirstName":"Sidekick","lastContactLastName":"Phone","lastContactDeviceId":0,"unreadCount":2,"bcc":"","lastUpdated":"2011-07-03T22:49:18-07:00","class":"com.zipwhip.website.data.dto.Conversation","deviceAddress":"device:/3134441232/0","lastNonDeletedMessageDate":"2011-07-03T22:49:27-07:00","deleted":false,"lastContactId":27629,"lastMessageDate":"2011-07-03T22:49:27-07:00","dtoParentId":1,"version":336,"lastContactMobileNumber":"2063981234","id":81312,"fingerprint":"2906579","new":false,"lastMessageBody":"hey, what's up duder?","address":"ptn:/2063983244","dateCreated":"2011-03-17T22:14:24-07:00","cc":"","deviceId":1},"scope":"device","reason":null,"tag":null,"event":"change","class":"com.zipwhip.signals.Signal","uuid":"787cc2-d094-4e6d-9b59-d8f56d","type":"conversation","uri":"/signal/conversation/change"}


Of course to get the output like that above, you have to send a text message to the phone that you logged in under. Once the text message hits that phone, assuming you have Zipwhip correctly installed on the phone, you will get a text message hitting your application instantaneously. You will see a signal called “/signal/message/receive” popping up in your console window.

That’s it. I hope you’ve enjoyed working with the Zipwhip API using sockets to receive real-time incoming text messages to your phone! Enjoy.

Filed under Tutorials Tagged with code, Java, text messaging, Zipwhip API

Tutorial: Using the Zipwhip API in Java

June 19, 2011 3 Comments

I’m new to the Zipwhip API so I figured I would share my experience sending out my first text message using the Zipwhip system. To follow along with this article you will need to get your hands on the Zipwhip API as a JAR file. It’s available here for download:

Zipwhip API Jar File (170KB) ZipwhipAPI.jar

Release Date: 6/18/2011

First, open up Eclipse and make a new Java project.

Call the project ZipwhipAPIExample. (BTW, you can zoom in on the screenshots by clicking them.)

You can leave the Source tab alone, however you will want to add the ZipwhipAPI Jar to the Libraries tab.

Make sure you download the ZipwhipAPI Jar from the link at the start of this article. Then, add it to the Libraries list by choosing “Add External JARs” and finding the file on your local computer. Make sure to add the Log4J Jar file as well since the ZipwhipAPI is dependant upon it. You will get compile errors if you don’t have Log4J somewhere in the build path.

You should now have a new project in your Package Explorer. You are ready to go.

Make a new Java class file by right-clicking the src folder and choosing “Class”.

Call your class “Example” after you’ve entered a package name of something like “com.yourcompany.zipwhipapi”. Make sure to also create a public static void main() method so you have an entry point for your Java app.

After you hit “Finish” you should see something similar to the following generated code.

Now, we’ll help you out with the code you should place into the Example.java file in order to send off your first text message using the Zipwhip API. Make sure you set your own mobile number and password in the code. If you don’t know what your password is, or you have never signed up for Zipwhip, you need to do it via your carrier website if your carrier supports Zipwhip. Zipwhip has contracts with most major U.S. carriers so please visit your carrier site or call your carrier to find out how to gain access.

Download source code below Example.java

package com.yourcompany.zipwhipapi;

import com.zipwhip.api.DefaultZipwhipClient;
import com.zipwhip.api.HttpConnection;
import com.zipwhip.api.ZipwhipClient;

public class Example {

    public static void main(String[] args) {

        HttpConnection connection = new HttpConnection();

        String mobileNumber = "3135551212";
        String password = "mypassword";

        try {
            connection.requestLogin(mobileNumber, password);
            ZipwhipClient zipwhipClient = new DefaultZipwhipClient(connection);

            // Ok, go ahead and send your message
            zipwhipClient.sendMessage("3134440002", "This is our first test SMS message.");

            System.out.println("Done sending message");

        } catch (Exception e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        }
    }
}

This is what your Eclipse window should look like when all of the code is done and ready to go.

That’s it. Have fun sending off text messages via Zipwhip’s spectacularly simple API. If you want to get fancy, try to use some of the other methods in the API that let you create contacts, create groups, receive messages back, let you setup a URL to be posted to when an SMS comes in, etc.

To learn how to receive text messages via the Zipwhip API you can read my next posting.

Filed under Tutorials Tagged with Eclipse, Java, Zipwhip API

Zipwhip's Blog

Tutorial: Using the Zipwhip API in Java to Popup Your Text Messages in a Bubble Window

Tutorial: Using the Zipwhip API in Java to Receive Text Messages via Sockets

Tutorial: Using the Zipwhip API in Java

Recent Posts

Archives

Like Us

Twitter

Follow “Zipwhip's Blog”

Share this:

Share this:

Share this:

Share this:

Share this:

Share this:

Share this:

Recent Posts

Archives

Follow “Zipwhip's Blog”