むしろ Twitter4J で twitter を勉強してみる (3) ： StatusMethods インターフェース (I)

さて、今回から twitter4j.Twitter インターフェースが拡張しているインターフェースを具体的に見ていきます（記事一覧）。　まぁ当面は Twitter4J のサイトにある「コード例」で使われているやつから攻めていきましょう。　まずは「1. スタテータスの更新」で使われているメソッド Twitter#updateStatus() が定義されているインターフェース、twitter4j.api.StatusMethods インターフェースをやっちゃいます。

参考 URL

• Twitter4J 「コード例」

StatusMethods インターフェース

StatusMethods インターフェースの定義はこんな感じです（JavaDoc）：

public interface StatusMethods{

    // ステータスの更新・取得・リツート・削除
    Status updateStatus(java.lang.String status)
    Status updateStatus(StatusUpdate latestStatus)
    Status showStatus(long id)
    Status retweetStatus(long statusId)
    Status destroyStatus(long statusId)

    // リツイートの取得
    ResponseList<Status> getRetweets(long statusId)
    ResponseList<User> getRetweetedBy(long statusId, Paging paging)
    IDs getRetweetedByIDs(long statusId, Paging paging)
}

定義されているメソッドは、大きく分けて「ステータスの更新・取得・リツート・削除」と「リツイート取得するもの」に分けられそうです：

• ステータスの更新・取得・リツート・削除
  • 更新 ： updateStatus()
  • 取得 ： showStatus()
  • リツイート ： retweetStatus()
  • 削除 ： destroyStatus()
• リツイートの取得
  • リツイートしたツイートを取得
  • リツイートしたユーザーを取得
  • リツイートしたユーザーを ID で取得

これはあくまで拙者の勝手な分類です。　で、今回は1つ目の「ステータスの更新・取得・リツイート・削除」に関するメソッドを見ていきます。

ステータスの更新・取得・リツイート・削除

「ステータスの更新・取得・リツイート・削除」に関するメソッドを見ていく前に、そもそも「ステータス (status)」とはなんぞや？というところから疑問。　と、StatusMethods インターフェースに定義されているメソッドをふも見ると Status インターフェースっていうのがあるじゃん！と、JavaDoc を見てみると「one single status of a user」だそうで・・・　うーむ。　まぁ、twitter って最初に「いまどうしてる？」って聞かれるので、それで更新するのは今の「状態・状況」ってことでいいんでしょうかね。　Twitter4J 的には Status インターフェースの仕様を見ていけばよさそうですが、それは後ほど。

「更新・取得・リツイート・削除」という並びを見ると、データベースの「CRUD」を思い浮かべますが、

• twitter ではツイートを削除できても修正ができない（「C」に対応するのが更新で、「U」に対応するものがない）
• twitter ではリツイートができる

ってあたりがデータベースとの違いしょうかね。　まぁ、違いはありつつも「twitter はツイート（というかステータス）のデータベースだ」という見方が役に立つこともあるかも知れないので（ないかも知れないけど）、頭の片隅においときましょうかね。

さて、「ステータスの更新・取得・リツイート・削除」をするメソッドは、

• updateStatus(String) : Status
• updateStatus(StatusUpdate) : Status
• showStatus(long) : Status
• retweetStatus(long) : Status
• destroyStatus(long) : Status

ですが、API 的には Status オブジェクトを返すメソッドを集めたとも言えます。

• ステータスの更新を行う updateStatus() メソッドはツイート内容を表す文字列、もしくは後で見る StatusUpdate クラスのインスタンスを引数にとります。
• 残りの取得・リツイート・削除に対応するメソッドは、それぞれの操作対象となるステータスを特定する ID の long 値を引数にとります。　ステータスの ID は、Status オブジェクトがあれば getId() メソッドで取得できます。

サンプル・コード

まぁ、簡単なサンプル見た方が早いですかね：

@Grab('org.twitter4j:twitter4j-core:[2.2.4,)')

import twitter4j.*

def twitter = new TwitterFactory().getInstance()

// ツイートの投稿
def status0 = twitter.updateStatus('Hello, Twitter4J World !')
long id = status0.getId()

// ツイートの取得
def status1 = twitter.showStatus(id)
assert status1.text == 'Hello, Twitter4J World !'

// リツイート
def status2 = twitter.retweet(120564920495513601L)
assert status2.isRetweet()

// ツイートの削除
def status3 = twitter.destroyStatus(id)
assert status3.text == 'Hello, Twitter4J World !'
    // ツイート削除後でも返り値の Status オブジェクトに対する処理は可能
try{
    twitter.showStatus(id)    // id による取得は不可
    assert false

}catch(TwitterException e){ assert true }

といった感じです。　ステータスの ID さえ取得できれば難しいことはないと思います。　StatusUpdate オブジェクトを使った更新は後ほど。

処理のイメージ図

updateStatus()

showStatus()

retweetStatus()

destroyStatus()

twitter のサイト上では

createStatus()

showStatus()

retweetStatus()



リツイートは自分のツイートのように扱われる場合もあります。
例えば、自分の公開プロフィール上でリツイートを確認できます。

destroyStatus()

「リツイート」や「お気に入り」の削除（取り消し）も同様にできます。

関連クラス

さて、以下では「ステータスの更新・取得・リツイート・削除」を行うメソッドで出てきたインターフェース、クラスをちょっと詳しく見ていきます。　出てきたのは

• twitter4j.Status インターフェース
• twitter4j.StatusUpdate クラス

の2つでした。

Status インターフェース

Status インターフェースは結構重要そうなインターフェースですね。　「ステータスとはなんぞや？」に対する答えは、このクラスを読み解けば分かるかもね。　Status インターフェースは getter メソッドのみが定義されているようで、immutable を想定しているようです。　実際、（提供されている）唯一の実装クラス StatusJSONImpl は immutable として実装されています。　型定義はこんなの（JavaDoc）：

public interface Status extends java.lang.Comparable<Status>, TwitterResponse, java.io.Serializable{ ... }

TwitterResponse インターフェースはいろいろなサブインターフェースがあるので、後日詳しく見ていきます（こちら）。　Comparable は何に対して比較するのか JavaDoc からは分かりませんでしたが、素直に考えると作成時刻（createdAt プロパティ）かなぁ（未確認）。

次は Status インターフェースの（JavaBean としての）プロパティを見ていきます。　結構たくさんのプロパティがあるので、独断と偏見で適当に分類しています：

• ステータスの種類を判定するプロパティ
• ツイート内容に関連するプロパティ
• リツイート、返信に関するプロパティ
• 付加情報に関するプロパティ
• スーパーインターフェース TwitterResponse から継承したプロパティ

上記で説明したように Status インターフェースは immutable （様）なので、プロパティと言っても getter （もしくは isXxxx()）メソッドがあるだけです。

まずはステータスの種類を判定するプロパティ：

プロパティ	型	備考
favorited	boolean	お気に入りかどうか
retweet	boolean	リツイートかどうか
truncated	boolean	???

これらは boolean 値のプロパティなので isXxxx() によって値を取得します。

次はツイート内容に関連するプロパティ：

プロパティ	型	備考
text	String	ツイートした内容
userMentionEntities	UserMentionEntity[]	言及したユーザー @xxxx
URLEntities	URLEntity[]	言及した URL
hashtagEntities	HashtagEntity[]	言及したハッシュタグ #xxxx
mediaEntities	MediaEntity[]	???

単純な内容は getText() によって取得できます。　それ以外のプロパティはツイート内容のテキストを解析して結果をオブジェクトとして返すようです。　ハッシュタグなどのテキスト内の位置なども取得可能。

続いてリツイート、返信 (reply) に関するプロパティ：

プロパティ	型	備考
retweetCount retweetedByMe retweetedStatus	long boolean Status	リツイート数 自分がリツイートしているかどうか リツイートされたステータス
inReplyToStatusId inReplyToUserId inReplyToScreenName	long long String	返信対象のステータス ID 返信対象のユーザー ID 返信対象のユーザーのスクリーン名

リツイート関連のメソッドは、まとめて書いてますが「普通のステータスに対するリツイート情報」か「リツイートのステータスに関する情報」か、どちらに対して使用するメソッドなのかを区別した方がよさそうです：

• retweetCount ： 普通のステータスまたはリツイートのステータス*1
• retweetedByMe ： 普通のステータス
• retweetedStatus ： リツイートのステータス

そして、ツイートを投稿するだけならあまり気にする必要のない付加情報。

プロパティ	型	備考
id	long	ステータスの ID。
user	User	ユーザー
contributors	long[]	複数で投稿を行っている場合の投稿者（参考）
source	String	ツイートを投稿したアプリケーションなど
createdAt	Date	投稿日時
place	Place	場所
geoLocation	GeoLocation	位置情報
annotations	Annotations	付加されたアノテーション（参考）

User インターフェースはこれまた重要そうな型なので、機会があればそのうち詳しく。

最後は TwitterResponse インターフェースから継承したプロパティ：

プロパティ	型	備考
accessLevel	int	取り得る値は TwitterResopnse に定義された定数
rateLimitStatus	RateLimitStatus

RateLimitStatus インターフェースに関しては JavaDoc 参照。

StatusUpdate クラス

StatusUpdate クラスは immutable な Status オブジェクトに対するビルダーのようなクラスです。　ただし、全てのプロパティを設定できるわけではなく、また直接 Status オブジェクトを構築できるわけでもありません。　クラス定義はこんな感じ（JavaDoc）：

package twitter4j;

public final class StatusUpdate implements java.io.Serializable{

    // コンストラクタ
    public StatusUpdate(String status)
    ...
}

定義されているメソッドには以下のようなものがあります：

プロパティ名	型	備考
getStatus()	java.lang.String	ツイート内容
getAnnotations() addAnnotation(Annotation annotation) setAnnotations(Annotations annotations) annotation(Annotation annotation) annotations(Annotations annotations)	Annotations void void StatusUpdate StatusUpdate	付加するアノテーション
getInReplyToStatusId() setInReplyToStatusId(long inReplyToStatusId) inReplyToStatusId(long inReplyToStatusId)	long void StatusUpdate	返信対象のステータス ID
getPlaceId() setPlaceId(String placeId) placeId(String placeId)	String void StatusUpdate	場所の ID
displayCoordinates(boolean displayCoordinates) setDisplayCoordinates(boolean displayCoordinates) isDisplayCoordinates()	StatusUpdate void boolean	座標を表示するかどうか
getLocation() setLocation(GeoLocation location) location(GeoLocation location)	GeoLocation void StatusUpdate	位置情報

getStutus() は投稿するツイートの文字列で、コンストラクタで指定し、取得のみできるプロパティです。　その他のプロパティには通常の JavaBean としての getter/setter と Python 風のプロパティ設定メソッドが定義されています：

使い方はこんな感じ：

StatusUpdate update = new StatusUpdate('Hello, Twitter4J World !')
update.annotation(...)
          .inReplyToStatusId(...)
          .placeId(...)
          .displayCoordinate(...)

Twitter twitter = new TwitterFactory().getInstance()
twitter.updateStatus(update)

通常のビルダーとは違って、StatusUpdate オブジェクトから Status オブジェクトを生成する必要はなく、StatusUpdate オブジェクトを直接 Twitter#updateStatus() メソッドに渡します。　更新されたステータスを取得したい場合は、updateStatus() メソッドの返り値を変数に代入して使用します。

Twitter API ポケットリファレンス (POCKET REFERENCE)

*1:リツイートのステータスに対して呼び出すとリツイートもとのステータスのリツイート数が返されてるっぽいです。