Net

Net

各種ネットワーク機能をラップしインターフェイスを共通化する。

new Net()

state() メソッドだけを持つ。通信用のプロパティは X.Pair によって隠蔽されています。

通信のキャンセル

kill() で通信待ち中はキャンセル&破棄、通信中の場合は通信の中断&破棄を行う。

イベント

X.Event.PROGRESS
通信進行状況
X.Event.SUCCESS
通信成功
X.Event.ERROR
通信エラー タイムアウトの場合、e.timeout == true で分かる。
X.Event.CANCELED
通信のユーザー、プログラムによるキャンセル。SUCCESS, ERROR, COMPLETE 後に kill()してもCANCELEDは呼ばれません。
X.Event.COMPLETE
通信完了。SUCCESS, ERROR, CANCELED 後に発生。

X.Net インスタンスは COMPLETE 後に自動で破棄される。

必須プロパティ

url
URL
type
'xhr', 'jsonp', 'form', 'image', 'img'
xhr
URL { url : 'hoge', type : 'xhr' } の省略形
jsonp
URL { url : 'hoge', type : 'jsonp' } の省略形
form
URL { url : 'hoge', type : 'form' } の省略形
image, img
URL { url : 'hoge', type : 'image' } の省略形

XHR 用プロパティ

method
'GET', 'POST' 未指定かつ postdata を設定している場合、'POST' になる。
params
url パラメータを object で渡すことが出来る。
postdata
string, object の場合は X.String.serialize される。
async
boolean
username
BASIC 認証
password
BASIC 認証
headers
object xhr.setRequestHeader する値
timeout
タイムアウト ms
cache
headers[ 'Pragma' ] = 'no-cache' 等を設定するか?
dataType
'text', 'json', 'xml', 'blob', 'arraybuffer' 等。xhr.responseType に指定する値
mimeType
'text/xml', 'audio/mpeg' 等。xhr.overrideMimeType する値
auth
X.OAuth2 インスタンス(OAuth2 サービスの定義)
getFullHeaders
getAllResponseHeaders() をパースしたハッシュを返す。値は配列になっている。XDR は Content-Type しか取得でいない。
canUse
未実装。gadget proxy, YQL, YPipes 等のマッシュアップの許可。現在は test : 'gadget' としている

JSONP 用プロパティ

params
url パラメータを object で渡すことが出来る。
callbackName
callback(json) コールバック名が固定されている際に指定。または &callback=hoge 以外の名前でコールバックを指定する場合に params と callbackName に書いておく。url パラメータに callback が無く、callbackName もない場合、フレームワーク内で自動で設定される
charset
ページと異なるjsonpを読み込む場合に指定 'EUC-JP', 'Shift-JIS' 等 script タグの charset に入る。https://code.google.com/p/ajaxzip3/issues/detail?id=5
useFireWall
異なるドメインに jsonp を読み込んだ後、xdomain iframe 通信を使ってデータを受け取る。不正なコードの実行を防ぐことが出来る(はず)、未実装

Form 用プロパティ

method
'GET' or 'POST'
params
パラメータ object は input タグの name & value に展開される。object を入れ子にすることはできない。
target
'_self', '_parent', '_top' の場合、ページから離脱する。target を指定せず同一ドメインの場合 response に body.innerHTML が返る。TODO X.Window
timeout
ms タイムアウト時間、省略可能
charset
未実装

Example
 // XHR - GET
var net = X.Net( { xhr : urlString } )
		.listen( X.Event.PROGRESS )
		.listenOnce( [ X.Event.SUCCESS, X.Event.ERROR, X.Event.TIMEOUT, X.Event.CANCELED ] );

// XHR - GET 
var net = X.Net( urlString );

// XHR - POST 
var net = X.Net( { xhr : urlString, postdata : myData } );

// JSONP
var net = X.Net( { jsonp : urlString, params : params, callbackName : callbackName, charset : charset, useFireWall : false } );

// Form
var net = X.Net( { form : urlString, method : 'POST', target : '_self', params : {} } );

// Image preload & getSize
var net = X.Net( { image : src, sizeDetection : true } );

// load <script>, <link>

Members

private _listeners :__Listeners__

イベントリスナをイベント名文字列や数値(5以上、フレームワーク内で定義)をキーとするArrayで記憶します。
Arrayには、{cbKind:種類,context:コンテキスト(thisObject),func:コールバック関数,supplement:サプリメントする引数の配列} というハッシュ、または関数が蓄えられています。

private _rawObject :Object

_rawObject には HTMLElement, window, document, XHR といったイベントターゲットオブジェクトを設定します。 _rawObject が設定されていると listen(), unlisten() 時に addEventListener(DOM Level2) や detachEvent(ie5~8), on~(DOM0) 等を操作します。 _rawObject は最初の listen() 前に設定しておかないと addEventListener 等が意図したように行われません。 X.Node では非同期に HTMLElement を生成していますが、要素生成以前に listen, unlisten を呼び出すことができます。これは適宜に X_EventDispatcher_toggleAllEvents を呼んで解決しているためです。

private _rawType :number

EventDispatcher がラップしている EventTarget オブジェクトのタイプです。
X_EventDispatcher_actualAddEvent で使用されます。
OTHER:0(node,window,document,Image,Audio), XHR:1, Silverlight:2

Methods

asyncDispatch(delay, e) → {number}

delay(ミリ秒)後にイベントを dispatch する。戻り値は uid = X.Timer.once() のタイマーID(数値)。X.Timer.remove(uid) でタイマーを解除して dispatch を中止できる。 kill() 時には内部でまだ呼ばれていないタイマーの X.Timer.remove() が行われる。インスタンスが破棄された後にタイマーが呼ばれることがないので神経質にならなくても安全に使える。

Parameters:
Name Type Description
delay number | eventHash | string ms 省略した場合は 0 として扱う asyncDispatch( 'myevent' ) -> asyncDispatch( 0, 'myevent' )
e eventHash | string | number イベントを表す数値、文字列、{ type : XXX, ... } なオブジェクト
Returns:
number X.Timer.add() の戻り値
Example
 this[ 'asyncDispatch' ]( 'myevent' );
// どちらのコードも同じ動作をする。
this.asyncDispatch( 0, 'myevent' );

Constructor(opt_rawObject)

X.EventDispatcher のコンストラクタの実体。
イベントターゲットをラップする場合、通常は new 時に渡します。
アプリケーション独自のイベントをやり取りしたいだけ、という場合イベントターゲットは指定しません。

Parameters:
Name Type Argument Description
opt_rawObject object optional 

dispatch(e) → {number}

登録されたイベントリスナを呼び出す。イベントリスナの返り値(数値)を OR したものを返す。イベントハッシュでなく、string|number を渡すと内部でイベントハッシュを作る。 dispatch のコールバック中で kill() が呼ばれた場合、実際の kill は、dispatch の終わりまで待機する。dispatch がネストする場合は全ての dispatch の完了で kill() する。__ClassBase__ も参照。 dispatch のコールバック中で listen() が呼ばれた場合、実際の listen は、dispatch の終わりまで待機する。dispatch がネストする場合は全ての dispatch の完了で listen() する。 dispatch のコールバック中で unlisten() が呼ばれた場合、即座に反映され削除されたイベントリスナーは呼ばれない。

Parameters:
Name Type Description
e eventHash | string | number
Returns:
number X.Callback で定義された数値(ビットフラグ)

instanceOf(klass) → {boolean}

インスタンスのクラスか?またはスーパークラスか?調べる。
instanceof 構文をサポートしない環境(IE5以下)を想定する場合、必ずこのメソッドを使用すること。
クラスのインスタンスか?だけ調べたい場合は this.constructor === klass が高速。

Parameters:
Name Type Description
klass __ClassBase__ クラス定義
Returns:
boolean

kill()

全ての動的メンバを削除して、インスタンスを破棄する。
インスタンスが X.EventDispatcher とそのサブクラスの場合、次の動作をする。

  1. X.Event.BEFORE_KILL_INSTANCE を発火する。戻り値のビットフラグに X_Callback.PREVENT_DEFAULT が立つ場合、破棄をキャンセルし X.Event.KILL_INSTANCE_CANCELED を発火する。この間に kill() が呼ばれても無視される。
  2. 破棄に進む場合は、X.Event.KILL_INSTANCE を発火する。
  3. dispatch 中は、インスタンスの全ての dispatch が終了するまで実際の破棄を待つ。
  4. 実際の破棄では、インスタンスのメンバの削除に加えて全てのイベントリスナを解除する。

listen() → {EventDispatcher}

イベントリスナを追加する。同一イベントに対して重複するリスナ(context, function, 引数 array が一致)の追加は無視される。 ユーザーが触ることは無いが、システム内部でロックフラグを立てたリスナは、立てられていないフラグとは区別される。 この仕組みによってシステムの登録したリスナを、システム外から不用意に削除されることを回避する。

Returns:
EventDispatcher チェインメソッド
Example
 // 'myEvent' に対して、 this コンテキストを指定して 、コールバック関数を渡す。
this[ 'listen' ]( 'myEvent', context, func );
// 'myEvent' に対して、 this コンテキストを指定して 、コールバック関数と追加の引数を渡す。
args = [ 'arg1', 'arg2', 3 ]; // unlisten( 'myEvent', context, func, args ) で使用するので Array も控えておく。
this[ 'listen' ]( 'myEvent', context, func, args );
// 'myEvent' に対して、 listener オブジェクトを渡す。listener は handleEvent という関数を持つオブジェクトのこと。
listener.handleEvent = function( e ){};
this[ 'listen' ]( 'myEvent', listener );
// 'myEvent' に対して、 listener オブジェクトと追加の引数を渡す。
listener.handleEvent = function( e, arg1, arg2, arg3 ){};
this[ 'listen' ]( 'myEvent', listener, [ arg1, arg2, arg3 ] );
// 'myEvent' に対して、 function を渡す。
this[ 'listen' ]( 'myEvent', onMyEvent );
// 'myEvent' に対して、 function と追加の引数を渡す。
this[ 'listen' ]( 'myEvent', onMyEvent, args );
// 次の二つは同じ動作です。 this コンテキストが与えられなかった場合、コールバックの this は発火元インスタンスになります。
this[ 'listen' ]( 'myEvent', this [, func [, args ] ] );
this[ 'listen' ]( 'myEvent' [, func [, args ] ] );
// 複数のイベントタイプを同時に登録。コールバックは同じ指定が使われる。
this[ 'listen' ]( [ 'open', 'close', 'ready' ], onUpdate );

listening(opt_type, opt_arg1, opt_arg2, opt_arg3) → {number|boolean}

イベントリスナの登録状況を真偽値で返す。戻り値が数値(index)の場合もあるが、これは内部のみで使用。

this.listening(); のように type を省略した場合、一つでも登録があれば true を返す。

this.listening( 'myevent' ); と type だけを与えた場合、その type に登録があれば true を返す。

type と イベントリスナの組み合わせが登録されているかを調べる場合は、listen 時の thisObject や args(Array) も一致させて渡す必要がある。

Parameters:
Name Type Description
opt_type string | number
opt_arg1 listener | function | Array | callbackHash
opt_arg2 function | Array
opt_arg3 Array
Returns:
number | boolean
Example
 
 this.listen( [ 'myevent', 'yourevent' ], this, onMyEvent, args = [ 1, 'a' ] );
 this.listening( 'myevent', this, onMyEvent, args ) === true;

listenOnce(type, opt_arg1=, opt_arg2=, opt_arg3=) → {EventDispatcher}

dispatch 時に自動で unlisten されるフラグを立てて listen する。

Parameters:
Name Type Argument Description
type string | number | Array.<string, number> 配列を指定した場合、複数のイベントタイプに対して同じコールバックを登録する。
opt_arg1= listener | function | Array optional 
opt_arg2= function | Array optional 
opt_arg3= Array optional  コールバック時の引数を配列に入れる。引数がひとつでも配列を使用する。省略した場合引数なし。unlisten() に使用するので、配列も適宜に保持しておくこと。
Returns:
EventDispatcher チェインメソッド

state()

現在の状態。1:順番待ち, 2:通信中, 3:通信完了フェーズ

Super(var_args) → {*}

関数は Constructor 内で使用します。クラス定義を辿ってスーパークラスのコンストラクタを呼び出します。
内部的には、呼び出したコンストラクタは配列に控え(X_Class_CALLING_SUPER)、呼び出したコンストラクタ内でさらに Super が呼ばれた場合、配列を元にさらにスーパーなコンストラクタを辿ります。

Parameters:
Name Type Argument Description
var_args ? repeatable  親コンストラクタを呼ぶ際に渡す任意の数の引数
Returns:
*
Example
 Constructor : function( arg1, arg2 ){
	this.Super( aeg1, arg2 );
}

superCall(myFunc, var_args) → {*}

myFunc について、スーパークラスで設定されている同名の関数を呼び出す。
低速な関数なので多用されるべきではありません!
第一引数に自身の(自身から参照できる)関数を指定します。内部では関数名を調べた上で prototype チェーンをゴリゴリ辿る、特別なことはしていません。
superCall と Super がネストする場合も現在のクラス階層を X_Class_SUPER_CALLER, X_Class_SUPER_STACKS を使って控えているので、意図した親関数が呼ばれます。
次の理由によって、関数名で辿ることは非推奨です。

  1. closur compiler でメソッド名が変更される
次の場合、意図した動作が得られません。
  1. 2つ以上の異なる名前で同じ関数がメンバーがいた場合
  2. サブクラスの prototype にスーパークラスと同じ関数をコピーしている
  3. 非関数でメンバーを上書きしている
  4. superCall 以外の手段で親関数を呼び、そのなかで superCall を呼んだ
通常の X.Class.create の書き方ではこのような状況は起きませんが、js はなんでもいろいろ出来てしまいますから…
参考:ES5なJavascriptでモダンなクラス的継承&スーパー呼び出し
original:Classical Inheritance in JavaScript

Parameters:
Name Type Argument Description
myFunc function | string オーバーライド済の自身の(自身から参照できる)関数。
var_args * repeatable  オーバーライド元関数に渡す任意の数の引数
Returns:
* オーバーライド元の関数を呼び出した戻り値。
Example
 return this.superCall( this.myFunc, param0, param1, ... );

unlisten() → {EventDispatcher}

イベントリスナの解除を行う。登録時と同じ引数を与える必要がある。kill() で自信に登録されたすべてのイベントが解除されるので、途中で解除されるイベント以外は kill() に任せてしまってよい。
他人に登録したイベントを解除せずに kill するのは NG。

Returns: