Static Export configuration
Static Export Configuration
For an introduction, see: Static Export
The Role of the OpenCms Error Handler during Static Export
The static export is always based on a specialized "Error-Handler". This errorhandler is registered for then complete OpenCms web application, so whenever a request points to nonexistent resources that belong to OpenCms, then the webserver will call the file-not-found handler of OpenCms and the errorhandler will take over.
If a request points to a location where a file should be exported (usually /opencms/export/), but is not yet exported then the errorhandler will cause the resource to be generated dynamically and will return the processing result to the client.
There are two ways, how this Handler is used to trigger the export of an existing file into the file system:
- If a user requests a file by calling its export location and if the file is not yet exported then the Error handler will take over, as described above. In this situation, OpenCms will always return the requested page to the client, as if it would exist in this location. But OpenCms can also be configured to write the requested resource into the file system along with that.
In this way, after the first failing request to an exportable resource, the file will exist in the file system to satisfy future requests for the same resource. This will speed all future requests for the given file, as all future requests can be directly satisfied with that exported file. This method is called Static Export On Demand. With this exported strategy, all exported files will be deleted from the file system, when something new is published. After that, whenever an exportable resource is requested, it will be re-created in its current state and written to the file system again.
- Another export method is called Static Export After Publish. It also uses the error handler's mechanism for exporting files. If this method of publishing is active, then OpenCms will export files as soon as changes are published. At that point, OpenCms will check the Export configuration for any resource sets that are defined there. When at least one file that belongs to a defined resource set is exported, then all other files that belong to that set are also exported. Resource sets are defined by one or more regular expressions and all files whose path matches one of these expressions, belongs to the given resource set.
If a file is exported, which belongs to no resource set at all, then all exportable files in the system are exported. The export is triggered by OpenCms calling it's own Errorhandler via HTTP for each file to be exported. As described above, the errorhandler will return the resulting page for this request. That page will then be exported into the file System. If a file has existed before, then it will be overwritten.
- Static Export after publish in the Background. (This can be done with a custom export handler.)
Because the Error handler is used for both Static Export methods, it must be working correctly, otherwise the export will fail. Also, for Static Export After Publish, the URL for exportable files must be corretly configured in the export configuration, so that opencms is able to call it's own errorhandler via HTTP.