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]
Made with Slides.com