PublicStorageオブジェクト
コンポーネント情報 | |
---|---|
version | 8.0 |
PublicStorage にアクセスするためのクラスです。
storage/public 配下のファイル・フォルダを対象とします
後述しますが、openAsBinary, createAsBinary, appendAsBinary, openAsText, createAsText, appendAsText API は、ファイルパスに加えて、引数に関数を受け取れるようになっています。
関数を渡して呼び出すことにより、Storage のユーザは close を呼び出す必要がなくなります。
close が、openAsBinary, createAsBinary, appendAsBinary, openAsText, createAsText, appendAsText API により確実に呼び出されることになるため、ファイルの解放漏れを予防できます。
そのため、openAsBinary, createAsBinary, appendAsBinary, openAsText, createAsText, appendAsText API を使用することを推奨します。
例1:
例2:
storage/public 配下のファイル・フォルダを対象とします
後述しますが、openAsBinary, createAsBinary, appendAsBinary, openAsText, createAsText, appendAsText API は、ファイルパスに加えて、引数に関数を受け取れるようになっています。
関数を渡して呼び出すことにより、Storage のユーザは close を呼び出す必要がなくなります。
close が、openAsBinary, createAsBinary, appendAsBinary, openAsText, createAsText, appendAsText API により確実に呼び出されることになるため、ファイルの解放漏れを予防できます。
そのため、openAsBinary, createAsBinary, appendAsBinary, openAsText, createAsText, appendAsText API を使用することを推奨します。
例1:
- 関数を渡さない例
var storage = new PublicStorage('test.txt'); var reader = storage.openAsText(); // reader は TextReader になります var line; while (line = reader.readLine()) { // 1行ずつ読み込みます Debug.print(line); } reader.close(); // 最後に、close を呼び出し、ストリームを閉じます
- openAsText の引数に、関数を渡す方法
(この方法では、ファイルオープン時の error も受け取ることが出来ることに注目してください。)
var storage = new PublicStorage('test.txt'); storage.openAsText(function(reader, error) { if (error != null) { Debug.print('ファイルのオープン中にエラーが起きました' + error.message); throw error; } var line; while (line = reader.readLine()) { // 1行ずつ読み込む Debug.print(line); } }); // この時点で reader が自動的に閉じられているので、ユーザは close を書く必要がありません
- eachLine メソッドを用いて一行ずつ表示する例
var storage = new PublicStorage('test.txt'); storage.openAsText(function(reader, error) { if (error != null) { Debug.print('ファイルのオープン中にエラーが起きました' + error.message); throw error; // 内部で生じた例外により openAsText を抜ける際にも、自動的に close が呼ばれます } reader.eachLine(function(line) { // 引数に指定した関数が1行毎に呼ばれます Debug.print(line); }); }); // この時点で reader が自動的に閉じられているので、ユーザは close を書く必要がありません
例2:
- openAsBinary, createAsBinary, appendAsBinary, openAsText, createAsText, appendAsText を使わずにファイルをコピーする例
ストリームを確実に閉じるためには、try ~ finally が必要なことに注目してください。
function copy(src, dest) { var reader = new PublicStorage(src).openAsText(undefined, 'UTF-8'); // TextReader を取得します。ファイルの内容は 'UTF-8' として読み込みます try { var writer = new PublicStorage(dest).createAsText(undefined, 'UTF-8'); // TextWriter を取得します。ファイルには 'UTF-8' として書き込みます try { reader.transferTo(writer); // transferTo メソッドを使用してデータを転送します } finally { writer.close(); } } finally { reader.close(); } }
- 上記の copy 関数を、openAsText, createAsText に関数を渡す方法で実装した例
openAsText, createAsText が、引数に渡された関数を実行終了後に close を自動的に呼び出すため、try ~ finally を書かずともリソース漏れがなくなります。
function copy(src, dest) { new PublicStorage(src).openAsText(function(reader, error) { if (error != null) { throw error; // 内部で生じた例外により openAsText を抜ける際にも、自動的に close が呼ばれます } new PublicStorage(dest).createAsText(function(writer, error) { if (error != null) { throw error; // 内部で生じた例外により createAsText, openAsText を抜ける際にも、自動的に close が呼ばれます } reader.transferTo(writer); }, 'UTF-8'); }, 'UTF-8'); }
コンストラクタの概要
PublicStorage (PublicStorage storage ) コンストラクタ。storage と同一のパスを指す PublicStorage を作成します。 |
PublicStorage (PublicStorage parent , String child ) コンストラクタ。parent/child を指す Storage を作成します。 |
PublicStorage (String path ) コンストラクタ。path を指す PublicStorage を作成します。 |
PublicStorage (String parent , String child ) コンストラクタ。parent/child を指す Storage を作成します。 |
メソッドの概要
返却値の型 | メソッド名 |
---|---|
ByteWriter | appendAsBinary (Function [callback] ) 追記用としてコンストラクタの引数に指定した path を開きます。 |
TextWriter | appendAsText (Function [callback] , String [charsetName] ) 追記用としてコンストラクタの引数に指定した path を開きます。 |
Boolean | append (String src , String [charsetName] ) 文字列を指定されたキャラセット名で変換しこのストレージに追記します。 |
Boolean | copy (PublicStorage to , Boolean [overwrite] ) このファイル、またはディレクトリを引数で指定された対象にコピーします。 |
ByteWriter | createAsBinary (Function [callback] ) 書き込み用としてコンストラクタの引数に指定した path を開きます。 |
TextWriter | createAsText (Function [callback] , String [charsetName] ) 書き込み用としてコンストラクタの引数に指定した path を開きます。 |
PublicStorage[] | directoriesStorages (Boolean [recursive] ) このストレージが示すディレクトリ内のディレクトリを示すストレージのコレクションを返します。 |
String[] | directories (Boolean [recursive] ) このストレージが示すディレクトリの配下にあるディレクトリのパスのコレクションを返します。 |
Boolean | exists () このストレージが示すファイルまたはディレクトリが存在するかどうかを判定します。 |
PublicStorage[] | filesStorages (Boolean recursive ) このストレージが示すディレクトリ内のファイルを示すストレージのコレクションを返します。 |
String[] | files (Boolean [recursive] ) このストレージが示すディレクトリの配下にあるファイルのパスのコレクションを返します。 |
String | getCanonicalPath () 正規化したパスを返します。 |
String | getName () このストレージが示すファイルまたはディレクトリの名前を返します。 |
PublicStorage | getParentStorage () 親ストレージを返します。 |
String | getParent () 親パスを返します。 |
String | getPath () パス名文字列を返します。 |
String | getRelativePath (PublicStorage target ) このストレージとの相対パスを返します。 |
PublicStorage | getRootStorage () ルートストレージを返します。 |
Boolean | isDirectory () このストレージが示すファイルがディレクトリであるかどうかを判定します。 |
Boolean | isFile () このストレージが示すファイルが普通のファイルかどうかを判定します。ファイルは、それがディレクトリではなく、システムに依存するほかの基準を満たす場合に「普通」のファイルと見なされます。 |
Number | lastModified () このストレージが示すファイルが最後に変更された時刻を返します。 |
Number | length () このストレージが指定されているファイルの長さを返します。パス名にディレクトリが指定されている場合、戻り値は指定されません。 |
PublicStorage[] | listStorages (Object [filterOrRecursive] ) このストレージが示すディレクトリ内のファイルおよびディレクトリを示すストレージのコレクションを返します。 |
String[] | list (Object [filterOrRecursive] ) このストレージが示すディレクトリの配下にあるファイル、および、ディレクトリのパスのコレクションを返します。 |
String | load () 非推奨 このストレージの内容を取得します。
旧 API からの置き換えを容易にするために用意してはいますが、新規の開発において、転送するファイルのサイズが大きくならない余程の確信が無い限りは、これらの API を使用しないで下さい。代わりに
openAsBinary, createAsBinary, appendAsBinary, openAsText, createAsText, appendAsText を使用してください
|
Boolean | makeDirectories () このストレージが示すディレクトリを生成します。 |
Boolean | move (String newPath ) このストレージが示すファイルを移動します。 |
ByteReader | openAsBinary (Function [callback] ) 読み込み用としてコンストラクタの引数に指定した path を開きます。 |
TextReader | openAsText (Function [callback] , String [charsetName] ) 読み込み用としてコンストラクタの引数に指定した path を開きます。 |
String | read (String [charsetName] ) 非推奨このストレージの内容を指定されたキャラセット名で変換し文字列で取得します。
旧 API からの置き換えを容易にするために用意してはいますが、新規の開発において、 転送するファイルのサイズが大きくならない余程の確信が無い限りは、これらの API を使用しないで下さい。代わりに
openAsBinary, createAsBinary, appendAsBinary, openAsText, createAsText, appendAsText を使用してください
|
Boolean | remove (Boolean [recursive] ) このストレージが示すファイルまたはディレクトリを削除します。 |
PublicStorage | resolve (String other ) このストレージから相対ストレージを返します。 |
Boolean | save (String byteStream ) ファイルの中身をこのストレージに書き込みます。 |
Boolean | write (String src , String [charsetName] ) 文字列を指定されたキャラセット名でこのストレージに書き込みます。 |
コンストラクタの詳細
PublicStorage (PublicStorage storage )
コンストラクタ。storage と同一のパスを指す PublicStorage を作成します。
パラメータ
|
PublicStorage (PublicStorage parent , String child )
コンストラクタ。parent/child を指す Storage を作成します。
パラメータ
|
PublicStorage (String path )
コンストラクタ。path を指す PublicStorage を作成します。
パラメータ
|
PublicStorage (String parent , String child )
コンストラクタ。parent/child を指す Storage を作成します。
パラメータ
|
メソッドの詳細
ByteWriter appendAsBinary (Function [callback] )
追記用としてコンストラクタの引数に指定した path を開きます。
callback が渡された場合、callback の第 1 引数に ByteWriter, 第 2 引数に Error を渡し、ファイルの close は API が自動で行います(エラーがなかった場合、第 2 引数は null が渡されます)。
パラメータ
返却値
|
TextWriter appendAsText (Function [callback] , String [charsetName] )
追記用としてコンストラクタの引数に指定した path を開きます。
callback が渡された場合、callback の第 1 引数に TextWriter, 第 2 引数に Error を渡し、ファイルの close は API が自動で行います(エラーがなかった場合、第 2 引数は null が渡されます)。
パラメータ
返却値
|
Boolean append (String src , String [charsetName] )
文字列を指定されたキャラセット名で変換しこのストレージに追記します。
パラメータ
返却値
|
Boolean copy (PublicStorage to , Boolean [overwrite] )
このファイル、またはディレクトリを引数で指定された対象にコピーします。
このインスタンスが存在しない場合:
パラメータ
返却値
|
ByteWriter createAsBinary (Function [callback] )
書き込み用としてコンストラクタの引数に指定した path を開きます。
callback が渡された場合、callback の第 1 引数に ByteWriter, 第 2 引数に Error を渡し、ファイルの close は API が自動で行います(エラーがなかった場合、第 2 引数は null が渡されます)。
パラメータ
返却値
|
TextWriter createAsText (Function [callback] , String [charsetName] )
書き込み用としてコンストラクタの引数に指定した path を開きます。
callback が渡された場合、callback の第 1 引数に TextWriter, 第 2 引数に Error を渡し、ファイルの close は API が自動で行います(エラーがなかった場合、第 2 引数は null が渡されます)。
パラメータ
返却値
|
PublicStorage[] directoriesStorages (Boolean [recursive] )
このストレージが示すディレクトリ内のディレクトリを示すストレージのコレクションを返します。
パラメータ
返却値
|
String[] directories (Boolean [recursive] )
このストレージが示すディレクトリの配下にあるディレクトリのパスのコレクションを返します。
パスは、このストレージのパスからの相対パスです。 ディレクトリが空の場合は空コレクションを返します。 このストレージがディレクトリを示さない場合は null を返します。 ROOT ┗directory-1 ┗directory-1-1 ┣directory-1-1-1 ┃┣directory-1-1-1-1 ┃┗file-1-1-1-2 ┣directory-1-1-2 ┣file-1-1-3 ┗file-1-1-4上記のようなファイル構成である場合、 directory-1-1に対してdirectories(false)を実行した場合の戻り値は以下の通りです。
パラメータ
返却値
|
Boolean exists ()
このストレージが示すファイルまたはディレクトリが存在するかどうかを判定します。
返却値
|
PublicStorage[] filesStorages (Boolean recursive )
このストレージが示すディレクトリ内のファイルを示すストレージのコレクションを返します。
パラメータ
返却値
|
String[] files (Boolean [recursive] )
このストレージが示すディレクトリの配下にあるファイルのパスのコレクションを返します。
パスは、このストレージのパスからの相対パスです。 ディレクトリが空の場合は空コレクションを返します。 このストレージがディレクトリを示さない場合は null を返します。 ROOT ┗directory-1 ┗directory-1-1 ┣directory-1-1-1 ┃┣directory-1-1-1-1 ┃┗file-1-1-1-2 ┣directory-1-1-2 ┣file-1-1-3 ┗file-1-1-4上記のようなファイル構成である場合、 directory-1-1に対してfiles(false)を実行した場合の戻り値は以下の通りです。
パラメータ
返却値
|
String getCanonicalPath ()
正規化したパスを返します。
返却値
|
String getName ()
このストレージが示すファイルまたはディレクトリの名前を返します。
返却値
|
PublicStorage getParentStorage ()
親ストレージを返します。
返却値
|
String getParent ()
親パスを返します。
返却値
|
String getPath ()
パス名文字列を返します。
返却値
|
String getRelativePath (PublicStorage target )
このストレージとの相対パスを返します。
パラメータ
返却値
|
PublicStorage getRootStorage ()
ルートストレージを返します。
返却値
|
Boolean isDirectory ()
このストレージが示すファイルがディレクトリであるかどうかを判定します。
返却値
|
Boolean isFile ()
このストレージが示すファイルが普通のファイルかどうかを判定します。ファイルは、それがディレクトリではなく、システムに依存するほかの基準を満たす場合に「普通」のファイルと見なされます。
アプリケーションが生成したディレクトリ以外のファイルは、必ず普通のファイルです。
返却値
|
Number lastModified ()
このストレージが示すファイルが最後に変更された時刻を返します。
返却値
|
Number length ()
このストレージが指定されているファイルの長さを返します。パス名にディレクトリが指定されている場合、戻り値は指定されません。
返却値
|
PublicStorage[] listStorages (Object [filterOrRecursive] )
このストレージが示すディレクトリ内のファイルおよびディレクトリを示すストレージのコレクションを返します。
パラメータ
返却値
|
String[] list (Object [filterOrRecursive] )
このストレージが示すディレクトリの配下にあるファイル、および、ディレクトリのパスのコレクションを返します。
パスは、このストレージのパスからの相対パスです。 引数にファイル名フィルタが渡された場合、関数 の第 1 引数に listを実行した SharePointStorage が、第 2 引数に 対象のファイル名 を渡します。 関数の戻り値がtrueである場合、対象が取得対象となります。 ディレクトリが空の場合は空コレクションを返します。 このストレージがディレクトリを示さない場合は null を返します。 ROOT ┗directory-1 ┗directory-1-1 ┣directory-1-1-1 ┃┣directory-1-1-1-1 ┃┗file-1-1-1-2 ┣directory-1-1-2 ┣file-1-1-3 ┗file-1-1-4上記のようなファイル構成である場合、 directory-1-1に対してlist(false)を実行した場合の戻り値は以下の通りです。
パラメータ
返却値
|
String load ()
非推奨
旧 API からの置き換えを容易にするために用意してはいますが、新規の開発において、転送するファイルのサイズが大きくならない余程の確信が無い限りは、これらの API を使用しないで下さい。代わりに
openAsBinary, createAsBinary, appendAsBinary, openAsText, createAsText, appendAsText を使用してください
このストレージの内容を取得します。
返却値
|
Boolean makeDirectories ()
このストレージが示すディレクトリを生成します。
返却値
|
Boolean move (String newPath )
このストレージが示すファイルを移動します。
パラメータ
返却値
|
ByteReader openAsBinary (Function [callback] )
読み込み用としてコンストラクタの引数に指定した path を開きます。
callbackが渡された場合、callback の第 1 引数に ByteReader, 第 2 引数に Error を渡し、ファイルの close は API が自動で行います(エラーがなかった場合、第 2 引数は null が渡されます)。
パラメータ
返却値
|
TextReader openAsText (Function [callback] , String [charsetName] )
読み込み用としてコンストラクタの引数に指定した path を開きます。
callback が渡された場合、callback の第 1 引数に TextReader, 第 2 引数に Error を渡し、ファイルの close は API が自動で行います(エラーがなかった場合、第 2 引数は null が渡されます)。
パラメータ
返却値
|
String read (String [charsetName] )
非推奨
旧 API からの置き換えを容易にするために用意してはいますが、新規の開発において、 転送するファイルのサイズが大きくならない余程の確信が無い限りは、これらの API を使用しないで下さい。代わりに
openAsBinary, createAsBinary, appendAsBinary, openAsText, createAsText, appendAsText を使用してください
このストレージの内容を指定されたキャラセット名で変換し文字列で取得します。
パラメータ
返却値
|
Boolean remove (Boolean [recursive] )
このストレージが示すファイルまたはディレクトリを削除します。
recursive に明示的に true が渡されたときのみ、再帰的に削除します。
パラメータ
返却値
|
PublicStorage resolve (String other )
このストレージから相対ストレージを返します。
現在のパスから other だけ移動した新しい PublicStorage を返す。 例: new PublicStorage('a/b/c').resolve('..') -> 'a/b' を指す PublicStorage
パラメータ
返却値
|
Boolean save (String byteStream )
ファイルの中身をこのストレージに書き込みます。
パラメータ
返却値
|
Boolean write (String src , String [charsetName] )
文字列を指定されたキャラセット名でこのストレージに書き込みます。
パラメータ
返却値
|