Wednesday, 29 February 2012

Registering a REST application in ColdFusion10



<- Previous Contents Next ->



PART-II
Tutorial on REST: Registering a REST application



Regitsering a REST application
  1. To access any REST resource you need to register an application either through admin or using restInitApplication().
  2. Registering REST application is required because ColdFusion scans for all the REST resources present in directory you registered
  3. It is also important for you to know that you CAN NOT repeat 'restpath' for one and more resources. That is why it is a better option to create multiple apps, so that you can repeat the restpath in different applications as per your need
  4. You should also know that change in any resource(REST cfc) of your application will need a refresh in applcation. You can refresh from Administrator or using restInitApplication()


Using restInitApplication(): You can register as well as refresh an application using this method

This function takes three attributes: restInitApplication(dir_path, mapping_name, default)
    • dir_path: This is absolute path of the directory where you have plcaed your REST cfc.
    • mapping_name: This name can be anything. But keep in mind that this name will be used URL to call any of the resources in this application. Also note that this is an optional attribute. If this attribute is not present then ColdFusion will try to pick this name from Application.cfc(this.name) applicable to this directory.
    • default: You can get rid of the mapping_name in URL. To do so you can set any one of the application as default. I will discuss/explain this later with an example.
  1. If there is no error thrown, means your application has been registered successfully, so its always better to catch the error using cfcatch block
  2. If there is already an application registered with the mapping_name and the dir_path you gave, then this function will REFRESH already registered app.
  3. But if you will try to register another directory with already registered mapping name, you will get an error


Using Administrator: You can also register an application using Administrator
  1. Go to Admin -> DATA & Services -> REST services
  2. Root Path: Browse the directory which you want to register as REST application
  3. Service Mapping: Give the name of your mapping. This name will be used in URL to call any of the resource present in this application. This is optional. If not given, ColdFusion will try to search for name in Application.cfc(this.name) applicable to that directory.
  4. default: You can get rid of the mapping_name in URL. To do so you can set any one of the application as default. I will discuss/explain this later with an example


Application outside webroot
  1. You can also register a directory as REST application which is not present in your webroot
  2. To do so you have to add a mapping for that directory in ColdFusion
  3. Then you can register using the absolute path or also using that mapping instead of absolute path.



Default application:

If you really do not like to use the application mapping name(IIT - example from previous chapter) for you REST services, there is an option available to do that. But I will personally recommend that if you are publishing your REST services in production, then you should use application mapping name to avoid conflicts and for better management.

To get rid of application name, all you need to do is, make that application as default. There are two ways to do it.
  1. Go to Administrator->REST Services page, edit that application, check the checkbox saying default and update it.
  2. Use below given code if you do not like to go to Admin.
<cfset restInitApplication(absolute_path, mapping_name, "default")>

This will set your application as default and to call your resource you need to hit this URL - "http://localhost:8500/rest/restpath" where restpath is the restpath of your resource.


Few points to remember using default:


Default application is given last preference when you call some resource. Let's say you have a resource with restpath: "one/two" in your default application and you have a resource: "two" in your application named as "one".

  1. So on calling this url: "http://127.0.0.1:8500/rest/one/two", resource with restpath: "two" will be served from application: "one". But if application: "one" is not present then resource "one/two" will be served from default application.
  2. On calling this url: "http://127.0.0.1:8500/rest/one/" (notice a forward slash in the end of url), you will get resource not found, because there is no resource with restpath: "/" in application: "one".
  3. On calling this url: "http://127.0.0.1:8500/rest/one", it will search for resource: "one" in default application because url doesn't has a forward-slash after "one".
There can only be one default application at a time.


Refresh Application:


Once you have registered your application, you might want to change few things in your resources and want to services to reflect the effect. But there is a small hindrance in that. The time you register an application, ColdFusion loads the resources present in that application in memory, so if you are making some changes in you application, you need to tell ColdFusion in some way to refresh the application so that it can reflect the changes.
To achieve this there is a concept of refreshing an application. This can be done in two ways. One is from Administrator-REST Services page you can refresh whichever application you want. But if you want to do it right away from you code, you can use restInitApplication() function.
The same function for registering an application is also used for refreshing an application. If you are calling this function for some application but that application is already registered, then it will refresh it. So the trick is very simple. If application is not registered then restInitApplication() will register it, whereas if it is registered already, then it will refresh it.
For refreshing a default application you need not pass the third attribute("default") but for registering you need to.

Please note that using this function is not recommended in Application.cfc, it might break things. You may use this function in any cfm.



Role of Application.cfc:


If you have Application.cfc in the directory you want to register, then there are few things you might want to know.

  1. this.name - If application name is given in application.cfc, then while registering the application mapping name becomes optional. If you will not give application mapping name then your application will be registered using the name given in application.cfc
  2. this.restsettings.skipcfcwitherror - This is a boolean attribute. Usually if there some compilation error in any of your REST enabled cfc, then while registering you will get an error and you application will not be registered. But if this attribute is true, then even if there are errors in some cfc's, the rest of the cfc's will be published and your application will be registered successfully. Please note that if this attribute is true and all the cfc's have error then error will be thrown that no rest resource found.
  3. this.restsettings.cfclocation - you can give comma separated list of the directory path in this attribute. While registering or refreshing an application ColdFusion will search for all the rest enabled cfc's in these directories too. Please note that in this case, cfc's in current folder will not be considered. If you want to include present directory too, you need to give value something like this: this.restsettings.cfclocation = "/myfolder, ." (notice a dot after myfolder, to include present directory)

Update/Delete an application:

  1. To update already registered application you can go to administrator or you can use same function restInitApplication(). Lets say there is an application with path as "/myfolder" and mapping name as "app1". Now if you call this function: restInitApplication("/myfolder", "app2"), your application registered with "app1" will get updated to "app2".
  2. Though for registration/refreshing/updation same method was used but fortunately there is a separate method for deleting the REST application :) restDeleteApplication(absolute_path). You just need to pass the absolute path of the application registered to delete it.


That will be enough for registering/updating/refreshing the REST applications. I guess so ;)


<- Previous Contents Next ->



Thanks,
Milan.

2 comments: