Orkut Application Platform

The orkut Client Library - Scraps

Bruno Oliveira - Developer Relations
December 2010

This section of the guide explains how to perform common operations involving scraps using the orkut Client Library. If you haven't read it yet, please read the Introduction to the Client Library first, since we'll assume you know how to perform the library and environment setup.

Contents:

Reading Scraps

To read the user's scraps, you can use a GetScrapsTx transaction, generated from the scrap transaction factory made available by your OrkutAdapter. The transaction allows you to indicate how many scraps you wish to retrieve and in which format (text or HTML).

Let's take a look at a snippet of code that lists the first 20 scraps that the user has:

BatchTransaction btx = orkad.newBatch();
GetScrapsTx tx = orkad.getScrapTF().getSelfScraps();
tx.setMessageFormat(GetScrapsTx.MessageFormat.FULL_HTML);
tx.setCount(20);
btx.add(tx);
say("Getting first 20 scraps...");
orkad.submitBatch(btx);
say("Done.");

if (tx.hasError()) {
   say("*** Error fetching scraps.");
   return;
}

int i;
say(String.valueOf(tx.getScrapCount()) + " scrap(s) returned");
for (i = 0; i < tx.getScrapCount(); i++) {
   ScrapEntry se = tx.getScrap(i);
   String id = nullsafe(se.getId());
   String fromName = se.hasFromUserProfile() ?
          (nullsafe(se.getFromUserProfile().getDisplayName())) : "?";
   String body = nullsafe(se.getBody());

   say("Scrap #" + String.valueOf(i) + " (id " + id + "):");
   say("From: " + fromName);
   say("Body: " + body);
   say("");
}

Again, like in previous sections, remember that nullsafe is our function that simply tests if the argument is null and returns the string "null" in that case; otherwise it returns its argument. This is just so we can print it without worrying about NullPointerException's.

So, as you can see in the code above, we are setting the number of scraps with setCount(20) and then we iterate through the results with getScrapCount() and getScrap(i), the latter of which returns a ScrapEntry object. Each ScrapEntry comes with a scrap ID (which you can use when replying to the scrap, as we will see shortly) and a body, and may come with the profile of the user who sent it. As always, be prepared to handle the case where any of these values is null, representing the case where that data is not available.

You can get someone else's scraps simply by replacing getSelfScraps() with getScrapsOf(id), where id is the ID of the person whose scraps you wish to read.

BatchTransaction btx = orkad.newBatch();
GetScrapsTx tx = orkad.getScrapTF().getScrapsOf(id);
...

Sending Scraps

Sending a scrap is accomplished by a WriteScrapTx transaction. There are two types of scrap sending operation: a plain send and a reply. Plain sends require the ID of the addressee and the message body; replies require the ID of the addressee, the ID of the scrap you are replying to and the body of the message.

For a plain send, create the transaction with writeScrap(personId,body):

WriteScrapTx tx = orkad.getScrapTF().writeScrap(personId,body);

Here, personId is the ID of the person you want to send the scrap to, and body is the message to send.

If, on the other hand, you are replying to a scrap, then you must also provide the ID of the scrap you are replying to. In this case, use the replyToScrap() function:

WriteScrapTx tx = orkad.getScrapTF().replyToScrap(personId,scrapId,body);

For more information about how to get scrap ID's, please see the previous section on loading scraps.

Submitting the scrap transaction is not different from any other transaction:

BatchTransaction btx = orkad.newBatch();
btx.add(tx);
orkad.submitBatch(btx);

Important: to protect the platform from spammers, sending scraps may require solving a captcha depending on the content, the number of recent requests and other factors. For more information on how to handle that, please read the Errors and Captchas section of this guide.

When to Send Scraps

Scraps are a personal form of communication and users are very sensitive to the relevance of what they receive. Therefore, scraps are more adequate for personal messages directed specifically at the addressee, and should not be used for bulk messaging, advertising or announcements. Nobody likes a spammer!

So, if you want to announce something that's not directed to a particular addressee, you should post it to the activity stream. See this section on activity transactions for more information.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.