説明
CFML 内で呼び出すことのできる関数を定義します。ColdFusion コンポーネントのメソッドを定義するために必要です。
履歴
ColdFusion 10： restPath 、httpMethod、produces、consumes
ColdFusion 8：
- returnformat 、secureJSON、verifyClient の各属性が追加されました。
- component が ReturnType 属性の有効な値として追加されました。
ColdFusion MX 7：description 属性が追加されました。また、 returntype 属性に XML 値が追加されました。ColdFusion MX：このタグが追加されました。
カテゴリ
関連項目
cfargument、cfcomponent、cfinterface、cfinvoke、cfinvokeargument、cfobject、cfproperty、cfreturn、SerializeJSON
シンタックス
<cffunction name = "method name" access = "method access" consumes="MIME types" description = "function description" displayName = "name" httpMethod="GET|PUT|POST|DELETE" hint = "hint text" output = "yes|no" produces="MIME type" returnFormat = "not specified|JSON|plain|WDDX" returnType = "data type" roles = "securityRoles" restPath="sub-resource path" secureJSON = "yes|no" verifyClient = "no|yes">
属性
属性 |
必須／オプション |
デフォルト |
説明 |
|---|---|---|---|
name |
必須 |
|
文字列です。 cfcomponent タグ内で使用されるコンポーネントメソッドを指定します。 |
access |
オプション |
public |
メソッドを呼び出すことができるクライアントセキュリティコンテキストです。使用できる値は次のとおりです。 · private：メソッドを宣言するコンポーネント、およびそれが定義されているコンポーネントを拡張するコンポーネントのみから使用できます。 · package：メソッドを宣言するコンポーネント、コンポーネントを拡張するコンポーネントまたはパッケージ内の他のコンポーネントでのみ使用できます。同じパッケージ内の CFC ページでメソッドを使用できます。 · public：ローカルで実行中のページまたはコンポーネントメソッドから使用できます。 · remote：ローカルまたはリモートで実行中のページまたはコンポーネントメソッドから使用できるほかに、URL、Flash または Web サービスを介してリモートクライアントから使用することができます。関数を Web サービスとしてパブリッシュする場合、このオプションは必須です。 |
description |
オプション |
|
関数を短いテキストで説明します。 |
displayname |
オプション |
|
CFC メソッドのパラメータの場合にのみ意味があります。イントロスペクションを使用して CFC についての情報を示すときに、関数名に続く括弧内に表示される値です。 |
hint |
オプション |
|
CFC メソッドのパラメータの場合にのみ意味があります。イントロスペクションを使用して CFC についての情報を示すときに表示されるテキストです。hint 属性の値は、関数の説明のシンタックス行の次に表示されます。 |
output |
オプション |
関数の本文は標準の CFML として処理されます。 |
関数がどのような条件下で HTML 出力を生成するかを指定します。 · yes：関数の本文全体が cfoutput タグ内にある場合と同様に処理されます。シャープ記号（#）で囲まれた変数名は、自動的に実際の値に置き換えられます。 · no：関数が cfsilent タグ内にある場合と同様に処理されます。 |
returnformat |
|
戻り値 を WDDX または XML として返します。説明を参照してください。 |
リモートの呼び出し元に返される値の形式です。この属性は、ローカルの呼び出し元に返される値の形式には影響しません。 · json ：リモートで値を返す前に、戻り値を JSON 形式にシリアル化します。 · wddx ：リモートで値を返す前に、戻り値を WDDX 形式にシリアル化します。 · plain：戻り値の型が ColdFusion で文字列に直接変換できる型であることを確認して、シリアル化せずに文字列値を返します。有効な形式には、数値や XML オブジェクトなどのすべての単純型が含まれます。戻り値が配列やバイナリ値などの複合型の場合は、エラーになります。属性として returntype を指定する場合、その値は any、boolean、date、 guid 、numeric、string、 uuid 、 variablename 、または XML でなければなりません。それ以外の場合はエラーになります。 |
| restpath | オプション | String | CFC で使用する サブリソース パスを指定します。 パス内には正規表現を含めることもできます。 |
returnType |
Web サービスの場合は必須、その他の場合はオプション |
any |
タイプ名の文字列です。関数の戻り値のデータ型を指定します。 · any · array · binary · boolean · component：戻り値は ColdFusion コンポーネントである必要があります。 · date · function · guid ：引数は次の形式の UUID または GUID でなければなりません。 xxxxxxxx - xxxx - xxxx - xxxx - xxxxxxxxxxxx x は 16 進数の 1 文字（0～9、A ～ F）を表します。 · numeric · query · string · struct · uuid ：引数は次の形式の ColdFusion UUID でなければなりません。 xxxxxxxx - xxxx - xxxx - xxxxxxxxxxxxxxxx x は 16 進数の 1 文字（0～9、A ～ F）を表します。 · variableName：ColdFusion 変数のネーミング規則に従った形式の文字列です。 · void：値を返しません。 · xml : Web サービス関数で CFML XML オブジェクトと XML 文字列を返すことができます。 · コンポーネント名： returntype 属性の値が上記のどれにも当てはまらない場合、ColdFusion はそれを ColdFusion コンポーネントの名前として扱います。関数を実行したときに、返された値が指定の名前を持つ CFC でない場合はエラーになります。 |
roles |
オプション |
" " （空） |
メソッドを呼び出すことができる ColdFusion セキュリティロールのリストをカンマで区切って指定します。指定のロールでログインしているユーザーだけがこの関数を実行できます。この属性を指定しない場合、すべてのユーザーがこのメソッドを呼び出すことができます。 |
secureJSON |
オプション |
「説明」を参照 |
リモートの呼び出しへの応答として関数が JSON 形式で返す値の前に、セキュリティの接頭辞を追加するかどうかを指定するブール値です。デフォルト値は Application.cfc ファイルの This.secureJSON 変数の値か、 cfapplication タグの secureJSON 属性の値です。{{secureJSON}} アプリケーションの設定が存在しない場合は Administrator のサーバーの設定／設定ページのシリアル化 JSON への接頭辞付加設定の値（デフォルト値は false）です。 |
verifyClient |
オプション |
no |
暗号化されたセキュリティトークンを含めるためにリモートの関数呼び出しが必要かどうかを指定するブール値です。ColdFusion AJAX アプリケーションでのみ使用します。詳しくは、『ColdFusion アプリケーションの開発』の「Ajax プログラミングのルールとテクニック」の「セキュリティの強化」を参照してください。 |
restPath |
オプション |
|
CFC で使用する サブリソース パスを指定します。 |
httpMethod |
|
|
使用する HTTP メソッドです 。 次のいずれかを指定する必要があります。 · GET：サーバーに情報をリクエストします。リクエストされた情報をサーバーが 識別するために必要なデータはすべて、 URL 内か {{cfhttp type="URL"}} タグ内に含まれている必要があります。 · POST：処理する情報をサーバーに送信します。1 つまたは複数の cfhttpparam タグが必要です。フォームに似たデータを送信するときによく使用されます。 · PUT：指定の URL にメッセージ本文を保管するようサーバーにリクエストします。このメソッドは、サーバーにファイルを送信するときに使用されます。 · DELETE：指定の URL を削除するようサーバーにリクエストします。 · HEAD：GET メソッドと同じですが、サーバーは応答でメッセージ本文を送信しません。このメソッドは、ハイパーテキストリンクの有効性やアクセシビリティのテスト、ドキュメントのタイプや修正時刻の確認またはサーバーのタイプの判別に使用します。HEAD を指定していない場合、デフォルトで GET メソッドが呼び出されます。ただし、 メッセージ本文 はレスポンス内で送信されません。 · OPTIONS：サーバーまたは指定の URL で使用できる通信オプションについての情報をリクエストします。このメソッドを使用すると、ColdFusion アプリケーションは、追加のサーバー 活動 を要求しなくても、URL に関連付けられているオプションや要件、あるいはサーバーの機能を判別することができます。OPTIONS を指定していない場合は、ColdFusion によって応答が送信されます。 |
produces |
オプション |
/ |
受け入れ可能な MIME タイプのカンマ区切りリストです。リソースが生成可能な MIME メディアタイプの表現を指定するために使用します（例：{{produces= "text /plain ,text / html "}}）。リソースが複数の MIME メディアタイプを生成可能な場合、選択される関数は、最も受け入れ可能なメディアタイプとしてクライアントで宣言されたメディアタイプに対応します。 メモ |
consumes |
オプション |
/ |
受け入れ可能な MIME タイプのカンマ区切りリストです（例：consumes="text/plain,text/ html "）。リソースが受け入れ可能（つまり使用可能）なクライアントからの MIME メディアタイプの表現を指定するために使用します。この値は、コンポーネントレベルの同じ属性よりも優先されます。 |
使用方法
cffunction タグを使用すると、ColdFusion のビルトイン関数と同じ方法で呼び出すことのできる関数を定義できます。ColdFusion コンポーネント（CFC）のメソッドを定義するには、cffunction タグを使用します。次の例は、ColdFusion Query オブジェクトを返す単純な CFC メソッドを定義するための cffunction タグの属性です。
<cffunction name="getEmployees" access="remote" returnType="query" hint="This query returns all records in the employee database. It candrill-down or narrow the search, based on optional input parameters.">
ColdFusion コンポーネントに対する cffunction タグの使用について詳しくは、『ColdFusion アプリケーションの開発』の「ColdFusion コンポーネントの構築と使用」を参照してください。
returnformat="json" が指定されている場合に関数からクエリが返されたときは、2 つのエントリ、列名の配列および列データ配列の配列を含む JSON オブジェクトにクエリがシリアル化されます。詳しくは、「SerializeJSON」を参照してください。
roles 属性を指定した場合、この関数は、指定したロールのいずれかに所属するユーザーがログインした場合にのみ実行されます。
returnType 属性に variableName を指定した場合、この関数は、ColdFusion の変数ネーミング規則に沿った文字列を返さなければなりません。つまり、文字、アンダースコア（_）または Unicode 通貨記号で始まり、文字、数字、アンダースコア、ピリオド、Unicode 通貨記号のみから成る文字列を返す必要があります。ColdFusion は、その値が既存の ColdFusion 変数に対応するかどうかをチェックしません。
例
<cfcomponent> <cffunction name="getEmp"> <cfquery name="empQuery" datasource="ExampleApps" > SELECT FIRSTNAME, LASTNAME, EMAIL FROM tblEmployees </cfquery> <cfreturn empQuery> </cffunction> <cffunction name="getDept"> <cfquery name="deptQuery" datasource="ExampleApps" > SELECT * FROM tblDepartments </cfquery> <cfreturn deptQuery> </cffunction> </cfcomponent>
例
<!--- component with attributes rest and restpath --->
<cfcomponent rest="true"
restpath="/crudService">
<!--- handle GET request (httpmethod),
take argument in restpath(restpath={customerID}),
return query data in json format(produces=text/json) --->
<cffunction name="getHandlerJSON"
access="remote"
httpmethod="GET"
restpath="{customerID}"
returntype="query"
produces="application/json">
<cfargument name="customerID"
required="true"
restargsource="Path"
type="numeric"/>
<cfset myQuery = queryNew("id,name",
"Integer,varchar",
[[1, "John"], [2, "Doe"]])>
<cfquery dbtype="query"
name="resultQuery">
select * from myQuery where id = #arguments.customerID#
</cfquery>
<cfreturn resultQuery>
</cffunction>
</cfcomponent>
