Building and Deploying AKZ Files
An Akula ZIP (AKZ) file is an archive file that you deploy to the Akula Server. The AKZ file defines the services in the app scope that handle requests and manipulates responses.
Deploying an AKZ file is not the same as deploying a WAR file on a Java app server. Rather, you are copying an archive file to the
AKULA_HOME/deploy directory of the Akula Server. The Akula Server explodes the AKZ file and copies the exploded contents to the appropriate directory so that clients can access it.
For information on setting the value of
AKULA_HOME , see Set up the Akula Server Environment.
This section describes the following topics:
Creating an AKZ file
The AKZ file that you deploy is an archive of your Akula project. It is also referred to as your app scope. For information about the structure of an app scope, see Akula Project Structure.
To create an AKZ file, you can use the Java
jar utility to archive the file; or, if using Maven, you can use the Akula archetype and Maven plugin to generate it automatically (for more information, see Creating AKZ Files Using Maven).
The following example archives all files in the current directory and sub-directories into an AKZ file called MyApp.akz:
jar cfM ../MyApp.akz *
The M switch instructs
jar to exclude the /
META-INF directory in the JAR file. This is optional, but recommended, so that your AKZ file does not contain unnecessary files. (The
f switches indicate that you want to [c]reate a new JAR [f]ile.)
For more information on using the Java
AKZ file names are case sensitive. Because the name of the AKZ file becomes part of the URL that clients use to access the app scope, the URLs are therefore also case sensitive. Also, if you use special characters in the AKZ file name, you might have to URL encode the name when making a request. As a result, try to avoid using special characters in the name of your AKZ file.
Before you deploy a AKZ file, be sure to edit your permissions so that the services are not open. If you do not specify permissions, services defined in a AKZ file will be accessible by anyone.
For more information, see Authorizing Users.
If you change permissions after you deployed an AKZ file, you must restart the Akula Server.
By default, the Akula Server creates an internal app scope named
Deploying a new AKZ file
To deploy a new AKZ file, copy it to the
AKULA_HOME/deploy directory and restart the server. The server creates a directory that matches the name of the AKZ file and explodes the contents of the AKZ file into the
AKULA_HOME/apps/app_scope_name directory. For example, if you copy the MyApp.akz file to the
/deploy directory, the Akula Server creates a
AKULA_HOME/apps/MyApp directory and explodes the contents of the AKZ file under that directory.
The following example shows the resulting directories after deploying the MyAppWorld.akz file, where
After deploying an AKZ file and restarting the app server, the app scope in the URL is the same as the name of the AKZ file. For example, if you deploy the MyApp.akz file, the app scope for those services is MyApp, as the following example shows:
Regardless of whether hot-deployment is enabled for Tomcat or your Java app server, you must restart your Akula Server after deploying a new AKZ file.
Do not create a new directory under the
AKULA_HOME/apps directory of the Akula Server. Instead, always deploy the AKZ file to the
/deploy directory and let Akula create the files and folders under the
/apps directory. If you manually create directories under
/apps, and later deploy an AKZ file, your changes to the app services in the
/apps directory will be lost.
Before deploying an AKZ file, be sure to enable or disable Developer Mode. If you are releasing an AKZ file into a production environment, disable Developer Mode. For more information, see Enabling and disabling Developer Mode.
For additional best practices when deploying an AKZ file, see Deploying a Production App Scope.
If your AKZ files are not appearing in the apps folder of your VERIVO_HOME directory after placing them in the deploy folder, refer to this KB article: http://support.verivo.com/entries/23339107-Vas-files-are-not-unpacking-in-apps-directory-after-placing-them-in-deploy-
Deploying an updated AKZ file
To deploy an updated AKZ file, modify the source and re-archive it with the Java jar utility. Be sure to name the archive with the *.akz extension. Then re-deploy the AKZ file by copying it to the
/deploy directory and replacing the existing AKZ file.
The Akula Server deletes the contents of the
AKULA_HOME/apps/app_scope_name directory, and then explodes the contents of the new AKZ file under
You must restart your container after deploying a new AKZ file or redeploying an updated AKZ file.
Do not delete or modify the already-exploded files in the
/apps/app_scope_name directory. If you do, the next time you re-deploy the AKZ file, your changes will be lost. The reason for this is that when you restart the server, all directories in the
AKULA_HOME/apps directory are deleted and redeployed from their originating AKZ files in the
/deploy directory. If you changed the exploded version of a file, the changes will be overwritten.
If you receive a "Scope not found" error when making a request, be sure that you deployed the AKZ file and that the name of the app scope (the name of the AKZ file) is correct in the URL. AKZ file names are case-sensitive, so ensure that you use proper case in the URL to match the AKZ file name. Also, check the log files to ensure that the AKZ file was properly unzipped. If it wasn't, the Akula log shows a fatal error similar to the following:
Fatal error: can't unzip archive c:\Users\nickdanger\verivo\deploy\MyApp.akz
This error can occur if you use a tool other than the Java
jar utility to archive your AKZ file.
Undeploying an AKZ file
To undeploy an AKZ file, delete the AKZ file from the
AKULA_HOME/deploy directory. The Akula Server removes the exploded contents from the
AKULA_HOME/apps directory as well.
You must restart your Java app server after undeploying an AKZ file.
Testing the AKZ file deployment
After deploying your AKZ file, you can test the app scope with a browser or tool that generates HTTP requests.
In most cases, details about an error are written to the Akula log file in the
If one app scope fails to start because of a configuration error, other app scopes should still run.
If the endpoint does not have any authorization associated with it, then you can use a browser for GET requests. For example, if your application gets data from an open API, then you can use a URL such as
If the endpoint requires authorization or a method other than GET, then you can use a tool such as RESTClient (for FireFox) or Simple REST Client (for Chrome), which lets you select different methods of requests (PUT, POST, DELETE, and UPDATE), as well as add tokens for authentication.
The following table describes some common errors you might get when testing your AKZ file:
|Ensure that your URL contains the correct name of the AKZ file. The name of the AKZ file defines the app scope for your project.|
|Ensure that you added "/data" in your request URL and that your endpoint matches the pattern used in your endpoint configuration file.|
No consumers available on endpoint
Ensure that the URI in the method of your endpoint configuration file matches the from route's URI in your route configuration file.
For example, if your endpoint configuration file contains the following:
Then your route configuration file must contain the following:
|Check that the prefixes for your custom (and built-in) components are correct in the route configuration file.|
When you deploy an AKZ file and re-start the Akula Server, Akula:
- Validates the contents of the AKZ file.
- Reads in configuration files.
- Loads class files and ensures that there are no classloading issues such as missing definitions or references.
- Updates the permissions table to match the AKZ file's permissions.xml file.
- Creates a new context for the app scope that the AKZ represents. Each context has its own classloader.
- Opens the endpoints.
Validating AKZ files
The Akula Server validates that the AKZ file uses the proper directory structure and that all mandatory files are available. If there is an invalid file, the app scope throws an error. Other app scopes will continue to run even if one app scope fails.
Validation errors most commonly occur when you use an archiving utility other than jar to create the AKZ file. You should only use the Java
jar utility to create AKZ files. You can optionally use the M switch, which excludes the
/META-INF directory from the AKZ file; for example:
jar cfM ../MyApp.akz *
Permissions are stored in a local database. When the server starts up, it reads the permissions.xml file for the Akula Server and adds permissions defined in that file to the database. You can also define permissions in an AKZ file. The permissions in the AKZ file are read when the AKZ file is deployed. For more information, see Authorizing Users.
The standard classloader uses the Java classpath. Each app also has its own child classloader, that loads all classes in the AKZ file's
/lib directories. The server adds the app context to the server's classpath when a new app is added to the server so that the classloader will find classes and JARs in the application context.
Creating the context
The app scope context is registered with the server so that the auth, data, manage, and other sub systems can access it at run time.
By default, the management endpoints are enabled for the current scope. App scope endpoints are disabled by default if this is the first time the app scope is deployed.
When releasing a version of the AKZ file into a production environment, disable Developer Mode. For more information, see Enabling and disabling Developer Mode.