Advanced Macromedia ColdFusion MX 7 Application Development
| Most ISPs or hosting companies provide site owners with a control panel for their site. A control panel is an application that provides site administration to the site owners, including such functionality as domain management, email configuration, FTP access, database administration, bandwidth statistics, disk space calculations, and the like. Conversely, intranet and other shared-host administrators are less inclined to provide site administration features to their customers. There is usually some sort of change review process that takes place before these administrators will implement even the slightest DSN change for developers. This is where the Admin API fits into the process. The Admin API allows ISPs to extend their current control-panel applications to allow site owners to have customized ColdFusion administration. Some control-panel applications may already leverage the ColdFusion ServiceFactory to provide the same functionality; however, the Admin API is the preferredand only supportedmethod. It also enables intranet administrators to provide end-user access to ColdFusion Administrator functionality without compromising security. This eliminates some of the overhead in change-control processes and facilitates the development life cycle. NOTE Although access to the ServiceFactory is legitimate coding and there are a number of sites and articles that explain how to mimic ColdFusion Administrator functionality (such as disabling data sources), Macromedia will only officially support issues originating from the Admin API.
The Façade Component
To properly and securely extend the Admin API to users, custom modules should be built that provide minimal exposure to its methods. These modules should implement a façade design pattern. In Design Patterns: Elements of Reusable Object-Oriented Software (Addison-Wesley 1995), the "Gang of Four" (Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides) state the following as the purpose of the façade: "Provide a unified interface to a set of interfaces in a subsystem. Façade defines a higher-level interface that makes the subsystem easier to use." For custom admin consoles, the façade is a ColdFusion component that interfaces with the Admin API modules (Figure 11.1). Code the façade component to expose only the Admin API methods that make sense to the client. For example, suppose the customer has a dedicated server and you want to allow the customer to manage data sources and debugging and logging. You would code a component that would interface with those Admin API modules. Listing 11.1 illustrates a façade component that limits access just to creating a MS Access Unicode data source, and adding an IP address to the debugging IP restriction list. Listing 11.1. façade.cfcFaçade Access to Admin API
[View full width] <cfcomponent displayname="Facade" hint="Provides custom interface to the Admin API"> <!---#### File name: facade.cfc Description: Template that provides access to Admin API methods Assumptions: Access to the Admin API code base (/CFIDE/adminapi) Author name and e-mail: Sarge (ssargent@macromedia.com) Date Created: February 28, 2005 ####---> <cffunction name="login" access="remote" returntype="any" output="false"
Figure 11.1. A façade pattern for accessing the Admin API components.
The facade.cfc provides an interface to the Admin API. Administrators make this component available to their users in a secured area of the server. Keeping the facade.cfc in a secure area helps minimize the risk of unauthorized or malicious access. In this example, the facade.cfc enables users to create a data source and modify the debugging IP restriction list. The following uses the facade.cfc to add the current IP address to the debugging list: <cfobject name="REQUEST.myAdminObj" component="ows.chapter11.façade"> <cfset REQUEST.myAdminObj.setIP()> The facade.cfc in Listing 11.1 illustrates one method of exposing only a subset of the Admin API. Limiting the functionality in the façade prevents unintentional system wide damage or disclosure of sensitive data. The ColdFusion Component Explorer shows the methods and properties of the facade.cfc (Figure 11.2). Figure 11.2. Component Explorer view of the façade component (facade.cfc).
TIP Best practice is to secure the Admin API directory with a sandbox and only allow access to it from the custom module.
The front-end to the facade.cfc is a simple self-submitting form that accepts settings from the user. The form processes the user input and makes the appropriate call to the façade methods. For example, to create a new DSN based on submitted values, the form action code calls as follows: <cfif isDefined('FORM.submit')> <cfset VARIABLES.argCol = StructNew()> <cfloop index="i" list="#FORM.fieldNames#"> <cfif NOT FindNoCase("submit", i)> <cfset StructInsert(VARIABLES.argCol, i, FORM[i])> </cfif> </cfloop> <cfset REQUEST.myAdminObj.setMSAccessUnicode(argumentCollection=#VARIABLES.argCol#)> Similarly, here is a call to register an IP address for debugging: <cfif isDefined('FORM.submit')> <cfset REQUEST.myAdminObj.setIP(FORM.ip)> <cfelseif isDefined('FORM.currentIP')> <cfset REQUEST.myAdminObj.setIP()> </cfif>
Listings 11.2 and 11.3 show the completed forms for the IP and DSN functionality. You can add as much complexity or simplicity to your admin console as you want. For example, you could develop a front-end that leverages an LDAP to provide authentication and authorization. You could also extend the LDAP entries to store properties (such as a list of CFXs, DSNs, and mappings) for individual sites, which you would then allow the authenticated user to administer for their site. The main idea is to have one façade component as the access point to the Admin API. Listing 11.2. dsnForm.cfnAdding a Data Source
[View full width] <cfsetting enablecfoutputonly="yes"> <!---#### File name: dsnForm.cfm Description: Form for adding new DSN with the MS Access Unicode driver Assumptions: Access to the Admin API code base (/CFIDE/adminapi) via facade.cfc Author name and e-mail: Sarge (ssargent@macromedia.com) Date Created: February 28, 2005 ####---> <!---#### Create a local variable to hold the structure of current ColdFusion DSNs. ####---> <cfset VARIABLES.currentDSN = REQUEST.myAdminObj.getDatasources()> <cfif isDefined('FORM.submit')> <cftry> <!---#### Create a local variable structure to pass to the facade method. ####---> <cfset VARIABLES.argCol = StructNew()> <!---#### Loop over the FORM fields and populate VARIABLES.argCol, removing the submit
Listing 11.3. ipForm.cfmAdding an IP for Debugging
[View full width] <cfsetting enablecfoutputonly="yes"> <!---#### File name: ipForm.cfm Description: Form for adding IP addresses to the Debugging IP Restriction List Assumptions: Access to the Admin API code base (/CFIDE/adminapi) via facade.cfc Author name and e-mail: Sarge (ssargent@macromedia.com) Date Created: February 28, 2005 ####---> <cftry><!---#### If an IP is submitted the pass it to the setIP method, otherwise setIP
|