|
Code (User.cfc)
1 <cfcomponent displayname="User">
2 <cffunction name="getCellularNumber" access="remote" returnType="string">
3 <cfargument name="userId" type="numeric" required="yes" default="0" />
4 <cfset var thisUserId = trim(arguments.userId) />
5 <cfset var thisUsersCellularNumber = "" />
6 <cfif thisUserId GT 0>
7 <cfquery name="qryGetUsersCellularNumber" datasource="#DSN#">
8 SELECT cellular
9 FROM tblUser
10 WHERE userId = <cfqueryparam cfsqltype="cf_sql_integer" value="#thisUserId#" />
11 </cfquery>
12 <cfif qryGetUsersCellularNumber.recordCount EQ 1>
13 <cfset var thisUsersCellularNumber = qryGetUsersCellularNumber.cellular />
14 </cfif>
15 </cfif>
16 <cfreturn thisUsersCellularNumber />
17 </cffunction>
18 </cfcomponent>
Back To Top
Line 1 - <cfcomponent displayname="User">.
The <cfcomponent> has many attributes with many options. Know your defaults and keep things simple. For example,
the displayname="User" is not required; however, I
included it for this web service example. This is assuming you are Publishing a web service; and, you are allowing your client (or public) to view the CFC (ColdFusion Component) for it´s required arguments to consume the web service. In this case, you will want the CFC location out in the open
where the public can browse to it; and, not within your normal CFC mapped location.
Publishing a web service is when you allow other websites to browse to your CFC (ColdFusion Component) location.
Consuming a web service is when you allow other websites to invoke your CFC (ColdFusion Component) method via remote access. Your server become´s the application service provider for use to other web-based applications.
Line 2 - <cffunction name="getCellularNumber" access="remote" returnType="string">.
There are three attibutes that are required within the <cffunction> when creating a web service.
1. name
2. returnType
3. access="remote"
By setting access="remote", you are allowing other servers to access this method.
Line 3 - <cfargument name="userId" type="numeric" default="0" />.
This method has one argument, the userId. The type="numeric" is added data verification.
If I were to add the " required="yes|no", it would be ignored because all arguments are required when invoked as a web service.
If the call to the method does not contain an argument with a numeric value, you have two options.
Option 1, we let the method break; and, maybe rightfully so, it should break and stop the their processing.
Option 2, I added the default="0";
so, if nothing was passed in, the default will pick up the 0; and, elegantly return nothing. However you want to address the argument error is up to you.
Line 4 - <cfset var thisUserId = trim(arguments.userId) />.
The var is a function scope. Function scoped variables (var and local) only exist within the <cfunction> tag and will ensure that the variables do not bleed outside of the <cfunction> tag.
Next, note that I am trimming the argument value that would be passed into the method. This will catch any spaces that the client may be passing in along with the userId.
Line 5 - <cfset var thisUsersCellularNumber = "" />.
I am setting the return variable to nothing here; because, if the code does not fall within the next if statement, this ensures me that the thisUsersCellularNumber
variable will be defined and the method will elegantly return nothing.
Line 6 - <cfif thisUserId GT 0>.
If the argument value passed in (thisUserId set from the arguments.userId) is not above 0, then there is no need to further process this request and elegantly return nothing.
Line 10 - WHERE userId = <cfqueryparam cfsqltype="cf_sql_integer" value="#thisUserId#" />.
I added the <cfqueryparam cfsqltype="cf_sql_integer" value="#thisUserId#" /> for higher security (to prevent SQL injection); although, we already
know that the method will error if the argument is not of type="numeric" on line 3.
Line 12 - 12 <cfif qryGetUsersCellularNumber.recordCount EQ 1>.
If a record was returned from the <cfquery>, I am setting the return variable (thisUsersCellularNumber) to the database value.
If a record was not returned from the database call, the return variable is already set to nothing and return elegantly without issue.
Line 13 - <cfset var thisUsersCellularNumber = qryGetUsersCellularNumber.cellular />.
I am setting the return variable (thisUsersCellularNumber) to the database value.
Note, I am using the var scope here again as I already did on line 5 above. If I don´t use the var keyword here again,
the <cfset> will create a new variable in the local variable scope (different scope, different variable with the same name);
and, be visible throughout the entire CFC (ColdFusion Component); what I refer too as bleeding. If that same varible is used in another location,
you may confuse your application.
Remember, the access="remote" is intended to be visible for the web service.
In this case (arguably most cases), the variable usage is only intended for inside of the method.
Line 16 - <cfreturn thisUsersCellularNumber />.
Return the variable with the returnType="string".
I don´t care about the format of how the cellular number is stored in the database; however, I could format the phone number. Whatever it is, that is how it will be returned.
Back To Top
A nice difference in a ColdFusion web service is that you don't have to create a WSDL file for your web service; although I could.
The server does it automatically for you.
In many cases, to consume a web service, you only need to know the URL of the CFC (ColdFusion Component).
A typical call to a web service (or remote method) might look something like:
https://example.com/cfcs/user.cfc?method=getCellularNumber&userId=2532
In a ColdFusion web service, the URL references the CFC (ColdFusion Component) like this:
https://example.com/cfcs/user.cfc?wsdl
whereas, the ?wsdl parameter tells ColdFusion to invoke the CFC as a web service.
In the older versions of ColdFusion; and, assuming you wantted to view CFC (ColdFusion Component), you were allowed to leave off the ?wsdl parameter; and,
ColdFusion would invoke the CFC Explorer to show the CFC (ColdFusion Component) self-documentation through introspection.
Another difference between consuming a regular web service vs. one written in ColdFusion; has to do with data types of the input and
output parameters. In ColdFusion, there is no need for data type mapping. This means that your web service can accept and return any
valid ColdFusion data types without worrying about conversion issues.
Back To Top
|