Lucee undocumented

Gert Franz, Rasia Switzerland

About me

Gert Franz
- Involved with Railo since day 1
- Into CFML for 16 years
- DBA, System architect
- CTO Rasia Ltd, CIO Rasia CH
Rasia is founding Member of the Lucee association

My evolution

Assembler > Basic > Clipper > Pascal > Delphi > Java > CFML > Lucee

What is this about?

ONE DOES NOT SIMPLY

DOCUMENT EVERYTHING HE HAS CODED

What does undocumented mean?

Documentation is improving (docs.lucee.org)
Some things are either not known to the CFML community
or just simply not documented

What will we be looking at?

Administration of Lucee
Coding gems
Unknown functionality
Other gems / uncategorized
Tips and tricks

Lucee Administrators

Tips and tricks around the administration

Configuration XML

Let's have a look at the XML first
location and structure

Reset the Lucee Admin password

At the top of the Lucee administrator XML's you will find the following entry

<cfLuceeConfiguration 
        default-hspw="23d82bcab39f7cbfc41e2e9f5d539482ae76d86646e58e113166f0f370da06b0"
        hspw="23d82bcab39f7cbfc41e2e9f5d539482ae76d86646e58e113166f0f370da06b0"
        salt="F7323339-8891-474F-B59F0D00CCB8BAB3" version="4.5">
    <cfabort/>
    ...
<cfLuceeConfiguration>

Compiling into RAM

This can speed up your server's performance

Can be changed to any resource

<file-system 
    deploy-directory="zip://d:\Gert\Lucee\classes.zip!cfclasses" 
    fld-directory="{lucee-web}/library/fld/" 
    temp-directory="{lucee-web}/temp/" 
    tld-directory="{lucee-web}/library/tld/">
</file-system>

<file-system 
    deploy-directory="ram://cfclasses" 
    fld-directory="{lucee-web}/library/fld/" 
    temp-directory="{lucee-web}/temp/" 
    tld-directory="{lucee-web}/library/tld/">
</file-system>

Lucee constants

If you have inspected the XML, you probably have noticed these entries

You can also define your own constants

<!-- 
Path placeholders:
	{lucee-web}: path to the lucee web directory typical "{web-root}/WEB-INF/lucee"
	{lucee-server}: path to the lucee server directory typical where the lucee.jar is located
	{lucee-config}: same as {lucee-server} in server context and same as {lucee-web} in web context}
	{temp-directory}: path to the temp directory of the current user of the system
	{home-directory}: path to the home directory of the current user of the system
	{web-root-directory}: path to the web root
	{system-directory}: path to the system directory
	{web-context-hash}: hash of the web context
-->

<constants>
    <constant name="log-file-dir" value="/storage/logfiles/myWeb" />
</constants>

Copy the XML file to maintain settings

at startup the configuration is read from XML
This means you can "export" it
Copy the file to any new context
Settings are maintained

Using the DEPLOY folder

located in the Lucee server directory
can be used to install extensions
can also be used for upgrading Lucee

While we are at it

drivers and templates for Lucee are located in

/lucee-server/context/context/admin

In there you will find all different kind of drivers
- Database Drivers (configure your own)
- Event gateway drivers
- Cache drivers
- log drivers
Also the global debugging templates are located there. You can edit them (but be aware, that they might be overwritten in case of an update)
Server admin plugins are stored there as well

Compile mappings - Lucee archives

You are all familiar with mappings
In Lucee there are tons of more possibilities
Compile mappings is very useful when
- When converting from ACF to Lucee
- Trying to reduce the performance hit for the first page request
- Check for Lucee errors
Create an archive for source protection and performance

Debugging

Use a different debugging template
much more information to find
especially about unscoped variables
scope-checker at 100% hit ratio
but be careful, it consumes 30% of performance

Lucee Quarantine mode

Lets you run Lucee in a READONLY way
This means that Lucee will NOT compile any CFM files anymore
Protects you from exploits (happened several times)
Only code you trust will be actually executed on your server
Additional RSA encryption possible
Deploying an application with the CFDEPLOY tool

Other mapping tricks

Map to a resource
Resources usable are:
- RAM
- ZIP
- FTP
- HTTP
- Database
- S3
- SFTP

Coding Gems

Lots of unknown or hidden stuff regarding coding with Lucee

cfapplication action="update"

Have you ever
- wanted to load mappings from a database
- store configuration in a separate file
- add mappings to existing ones
- configure other application settings at a later time?
Let's have a look

sleeping and other nice additions

Sometimes it is necessary to pause the code
I mostly use it in event gateways or to visualize an effect (eg. long running query)
Look at the following code. It contains some nice additions in Lucee

<cfscript>
	myArr = "1,2,3,4,5".listToArray();
	myArr.append(6).append(7).append(8).append(9).append(10);
	myArr.each( function(iValue) {
		sleep(1000);
		echo(iValue & "<br>");
		flush;
		}, true, 2);
</cfscript>

how about loops

Looping is possible in many ways
index and item confusion
key and value introduced
looping over dates possible
for in works with all kinds of types
let's have a look

other nice coding additions

Cached functions
Handling the page cache
Closures for filters

Unknown functionality

Functions or tags few people know or use

Query functions

querySlice(), querySort()
queryColumnData()
- useful when query columns are dynamic
- when columns contain complex data
While we are at queries...
- cfquery returntype

Documentation functions

getFunctionList()
getFunctionData()
getTagList()
getTagData()

Other functions

getCurrentContext()
pagePoolList()
pagePoolClear()
_internalRequest()
fileInfo() - similar to CFFILE action="info"
isEmpty()
contractPath()
htmlParse()

Trial and error

CFRETRY tag
- allows you to retry a failed action
- Have a look at the following code

Planned for Lucee 5.2
- cftimeout time="10"
- expects the surrounded code block to execute within 10s, otherwise an exception is thrown

<cftry>
    <cffile action= "write" file="D:\test\myFile.txt">
    Some content for the file.
    </cffile>
    <cfcatch>
        <cfif !directoryExists("D:\test")>
            <cfdirectory action="create" directory="D:\test">
            <cfretry>
        </cfif>
    </cfcatch>
</cftry>

Other Gems

Other gems hidden in Lucee

Gems in CFScript

You can use <> in cfscript
or all other boolean JS operators
=== checks for same instance
general usage of tags in cfscript
assigning results to new variables

Miscelaneous

All pathes (except include) can be absolute or relative
cachedWithin accepts the value "request"
cachedWithin can also be a number

Extending Lucee

Do you have a library you use in your company?
You would like to extend the functionality of Lucee tags?
Write them yourself
- Either for one Context or global
- Just by writing one single file
- Caution: overwrites existing functions

One of my favorite gems

CFAdmin action="surveillance"
- Allows you to see what runs on your server
- Returns an array with all running requests
- contains very interesting information
  - all debugging information
  - all variables
  - CGI scope
  - Request scope
  - and a lot more

How about another CFAdmin gem

CFAdmin action="reload"
- You know now that the complete configuration is stored in the lucee-web.xml.cfm and lucee-server.xml
- these are loaded when the server starts and whenever a change is made in the admin
- if you change the admin file directly (or copy it) reload it with the above code

Tips and tricks

Things that make your life as a Lucee dev easier or faster

Using CFDump

first of all there are some nice attributes
- eval
- output = "debug"
- format = "simple" (for email & Outlook)
- showUDFs = "false"
Just hover over any part and you'll see where the dump comes from
Check out all the attributes under:
/lucee-server/context/library/tag/dump.cfc
Define the default attribute value like this:
- this.tag.cfdump.format="simple";

Lazy queries

Normally when you pull a query, Lucee:
- Opens a connection to the database
- Executes the query on the DB
- Returns the data
- Converts the Java resultset into a Lucee Query
Welcome Lazy queries. Now Lucee
- Opens a connection to the database
- Executes the SQL on the DB
- only returns the number of records (invisible for the user)
- Keeps the connection open while you browse through the records

Parallel threads in the each functions

Usable with any each function
Very useful when every operation is more time consuming
Finishes when all threads are done
by default uses 10 threads
Not adviseable for fast operations (<5ms)

Using the class files

Nice little gem regarding the class files
can be used instead of the actual CFM file
just needs to be named exactly as the original
can be used to protect single files
let's try it out

coding tips and tricks

cfthread type task
dynamic function calls
getMetaData
onRequest call even without the file existing
tag default attributes
trace action="follow"
using returnvalues from functions as variables somefunction()[3]