Unlike traditional file-based development environments, the Oracle APEX technology is designed as a centralized repository-based development environment, where processing, data manipulation and business logic is executed directly within the database. In such an architecture, an APEX application is deployed using a single export file containing the complete definition of the application.
The generated APEX Export file can be quite voluminous. Because of the nature of the SQL format, a very simple application can represent over 50K lines of code. The APEX Export file containing the APEX application definition is deployed alongside other scripts (DDL, packages, views, etc.) which need to be exported as well.
The APEX Export file has not been designed to be used with external lifecycle management (or version control) tools. Since the APEX Export file is the only output produced by the system which contains the code definition, it is currently used by developers as the input into external version control tools.
In its current state, the APEX Export file greatly limits the use of the change management functionalities found in version control tools, given the lack of a file-structure required by these external versioning tools.
APEXcl is a process which extracts the application definition from the Oracle APEX repository, deconstructs and translates the code into individual components (or artifacts) and sorts the data into a clear, logical and hierarchical file structure which can be used as an input to external versioning software.
This document explains how APEXcl fits in the architecture of a typical APEX application deployment and version control process.
Version control tools
The context of version control tools is important to understand to appreciate the full potential of APEXcl.
Version Control Systems (VCS): A version control system is the architecture that records changes to a file or set of files throughout the development lifecycle. Popular version control systems are Git and SVN (Subversion). APEXcl is compatible with both systems.
Platforms: Hosting of these systems is performed on platforms such as GitHub, BitBucket and GitLab for Git, and Tortoise for SVN. These platforms offer a number of functionalities useful in development lifecycle management, namely in facilitating code review, code control, and history management.
Client Applications: A client application will integrate Git into a user’s operating systems. Examples would be Sourcetree, GitHub Desktop, Visual Studio Code, Tortoise SVN, etc.
For the purpose of keeping this documentation simple, we will use Git as the VCS, hosted on the GitLab platform, using the client application Visual Studio Code.
Deployment process of an APEX application (currently, without APEXcl)
Generated Export Files (currently, without APEXcl)
The deployment of a typical APEX application generally requires the generation of two sets of files:
- The APEX application export file
- The DDL, packages, views, and other objects that are required for the app to function properly
The files generated in the course of a deployment of the application are committed (or saved) on a VCS.
Repository structure (currently, without APEXcl)
A typical APEX repository on the VC platform can be structured in many ways, but best practices would have the repository organized by object types.
Current Version Control process (currently, without APEXcl)
As an input, version control platforms use files which contain the individual artifacts of an application. In the case of Oracle APEX, such structured files are nonexistent since processing, data manipulation and business logic is executed directly within the database. As such, the only output currently available to be used in a version control platform (input) is the APEX Export file.
Input File: The APEX Export function generates a single voluminous SQL file that contains all the elements that exist inside the application: shared components, pages, regions, etc. This voluminous SQL file contains encoded characters and identification keys (IDs) that distract from the actual content of the application. It is not only hard to read and search, but since it is not logically structured, it does not allow the use of most functionalities on version control software.
Deployment process for an APEX application (with APEXcl)
APEXcl does not replace the regular APEX export mechanism, but rather adds a new layer of information (files) to be added on your version control system repository.
Each user (developer) installs APEXcl on his or her workstation. APEXcl connects to the same Oracle environment/database where the APEX application resides, extracts the application definition, and generates hundreds (or thousands) of smaller readable files structured in a folder tree. These generated files are in turn committed, or saved, on the same repository as the project.
Repository structure (with APEXcl)
The creation of an APEX directory at the root of the VC repository is recommended. The APEXcl export can then be saved under an apexcl subdirectory.
The above screenshot shows a simplified export. Thousands of files will be exported here.
APEXcl Output (and input into VC software)
The APEXcl process performs four key functions: (1) the extraction of individual artifacts from within the repository, (2) the breakdown and conversion of some Oracle APEX proprietary artifacts not exportable as individual components, (3) the sorting of individual artifacts into a logical and hierarchical file structure , and (4) the display of the exported individual artifacts in their respective programming languages such as JSON, SQL, JS, CSS, HTML, etc.
The generated folder structure or “file tree” in the APEXcl output (the APEXcl Export file) emulates the way the code for a project, application or software component is typically organized in traditional file-based development environments. It breaks down the code to a sufficiently granular level to enable the use of code management functionalities of VC software.