Configuring Apex Listener Version 2

“Where is the listenerConfigure page?”

That seems to be a common question when people attempt to deploy the Apex Listener Version 2.

Version 2 of the Apex listener is very different than version one. The configuration and maintenance is no longer done through web pages, but either through the command line or through SQL Developer. In this post I’ll try to explain how to configuration via the command line is made. I’ll dedicate another post to configuring the listener through SQL Developer.

In my example I have downloaded and unzipped the apex listener into the directory /u01/cmr. You will probably choose a different path, so make sure you substitute your path whenever necessary.

Before you configure the database connection of the listener, it is good to specify the directory where the configuration files will be stored. If you don’t do that, then the config files will be stored in /tmp/apex, which is not a good place.

To specify the configuration directory for the apex listener, navigate to the directory where you unzipped the listener files (/u01/cmr) and run:

java -jar apex.war configdir /u01/cmr

Note that whenever you run the java -jar apex.war command, it changes the files inside the apex.war archive. In this case I just picked the same directory where I  unzipped the files. The listener will create an apex directory here.

Now that we know where the configuration files will be, lets configure the database connection:

java -jar apex.war setup
 $ java -jar apex.war setup
 Feb 19, 2013 1:39:11 PM oracle.dbtools.common.config.file.ConfigurationFolder logConfigFolder
 INFO: Using configuration folder: /u01/cmr/apex
 Enter the name of the database server [localhost]:
 Enter the database listen port [1521]:
 Enter 1 to specify the database service name, or 2 to specify the database SID [1]:2
 Enter the database SID [xe]:vrep
 Enter the database user name [APEX_PUBLIC_USER]:
 Enter the database password for APEX_PUBLIC_USER:
 Confirm password:
 Enter 1 to enter passwords for the RESTful Services database users (APEX_LISTENER,APEX_REST_PUBLIC_USER), 2 to use the same password as used for APEX_PUBLIC_USER or, 3 to skip this step [1]:3
 Feb 19, 2013 1:39:50 PM oracle.dbtools.common.config.file.ConfigurationFiles update
 INFO: Updated configurations: apex

After this process is complete, you will find a newly created directory inside your config dir. Note that the name of the configuration folder is mentioned on top of the program output. The listener is now ready to be either run in standalone mode or to be deployed to your web server. You can run the listener in standalone mode to test the database connection:

$ java -jar apex.war standalone --apex-images /u01/apex/images

Note that I included the argument –apex-images. This will let the listener know from which directory to pull the images. In my case I unzipped the Apex installation files into /u01. When you run the command, the last line of the screen output will tell you the URL for connecting to Apex. If everything works, deploy your file to your web server.  That process hasn’t changed from version 1.
FYI: Inside the apex/ configuration directory is a file named which contains the port number and the images directory. This file is read when the listener starts up in standalone mode.

21 thoughts on “Configuring Apex Listener Version 2

  • February 21, 2013 at 2:34 pm

    Thanks for the post. The implementation of the first version of the ApEx Listener was painful. I usually resorted to the PL/SQL Gateway. I look forward to any additional information about the ApEx Listener you care to share.

  • May 7, 2013 at 1:34 pm

    I have to disagree with Bryant post. With all due respect, the configuration of the Listener in 1.1.4 was far better than 2.0. Using the command-line? This is a step backward.

  • May 7, 2013 at 1:39 pm

    I did enjoy your post and found it very helpful though … thanks for taking the time to document this process so clearly.

  • May 7, 2013 at 1:52 pm

    Also, where is the apex-config.xml file? (This is probably a misunderstanding on my part). And is there a simple way to determine what version of the APEX Listener one is running? I have it deployed as a web app on Glassfish 3.1.2.
    Thanks in advance.

  • May 7, 2013 at 3:58 pm

    to see which version of the listener is running, look at the web.xml file of the Deployment Descriptor in GlassFish.
    Go to GlassFish administration -> Applications -> apex, click the Descriptor tab, click the WEB-INF/web.xml link.
    This will display the web.xml file. Look for a tag near the top of the file. It should read something like this:



  • May 8, 2013 at 9:21 am

    Excellent Chris, I found the version of the APEX Listener as you described above.
    Is there still a apex-config.xml file that is created? Because I can’t find it on my Linux (CentOS) server. Please advise on where this file went.
    Thanks again for your clear explanation and assistance.


  • May 10, 2013 at 9:31 am

    in version 2 of the apex listener there is no longer an apex-config.xml file. All configuration is inside the apex.war and the configuration directory that is specified in the configdir parameter during setup.


  • May 21, 2013 at 9:29 am

    Thanks for your latest reply (5/10/13). It seems I can no longer get to the listenerConfigure URL and I can no longer access APEX. In past versions this was usually due to the apex-config.xml being placed in the /tmp directory (by default) and the file being deleted by a scheduled Linux process to clean /tmp. And in the past I modified the web.xml file to place the apex-config.xml in another directory. But as you correctly stated, the apex-config.xml file no longer exists. So I am at a lost as to what could be causing this. I am a newbie to APEX Listener 2.x. Please advise.

  • May 22, 2013 at 3:39 pm

    If the connection to Apex worked previously and has stopped all of a sudden, the first two things i would check are: 1. is the database up?, 2. is the listener running.
    Are you running in standalone mode?

  • May 30, 2013 at 4:16 pm

    My listener is deployed to GlassFish 3.1.2. Is there a typo in the Oracle docs? For ‘Deploying to Oracle GlassFish Server’, ‘Create the Web Archive for Oracle Application Express Images’, the doc states to use the command

    java -jar apex.war static \images

    then later refers to deploying the i.war file to GlassFish

    Shouldn’t this be java -jar i.war static \images ??


  • May 30, 2013 at 5:01 pm

    I guess I was incorrect as I was able to deploy. But that section of the docs is confusing about the i.war file.
    (1) The app does not launch right after I deploy the .war files. I have to go into GlassFish and launch the ‘apex’ application.
    (2) The i.war file — should that be enabled or disabled? And it should be a separate app named ‘i’? The docs just say to repeat the steps but that would include naming the i.war deployed app ‘apex’, which of course already exists. Some clarification is needed on the deployment of the i.war file — more than just ‘repeat the above steps’.
    Please comment and thanks in advance.

  • May 31, 2013 at 10:55 am

    As stated correctly:

    “Before you configure the database connection of the listener, it is good to specify the directory where the configuration files will be stored. If you don’t do that, then the config files will be stored in /tmp/apex, which is not a good place.”

    I consider this to be a ‘bug’ or bad design decision on Oracle’s part since most *nix/Linux systems will have a process to clean the /tmp directory. Who can be contacted so that this default directory is changed?

    My 2 cents.

  • May 31, 2013 at 11:00 am

    1) The deployed files get read when you launch the ‘apex’ application the new .
    2) The apex.war knows about the i.war when you deploy it. I’m not sure about dis-/enabling it.
    The docs could be written a bit better indeed.

  • May 31, 2013 at 11:01 am

    That was the problem with v1, too. My apex config file disappeared occasionally until i put it into a different directory.

  • June 12, 2013 at 8:49 am

    Hello Christoph,
    I was wondering if you could give some input on another topic. When I upgrade from APEX 4.1.1 to APEX 4.2.2 I am forced to change the ADMIN password after logging in as ADMIN. I then change the ADMIN password a second time and uncheck the box that says ‘force user to change password on login’ (or something like that). After all this, I can no longer login as ADMIN, even if I change the ADMIN password with the script apxchpwd.sql. In fact the account eventually becomes locked. Now I can unlock the account but, after some research, I have not been able to find a solution to this dilemma except suggestions to reinstall APEX 4.2.2.
    Any ideas would be appreciated. Thx.

  • June 12, 2013 at 10:50 am

    Hello Christoph,
    Here is the solution to my previous issue. You can add it to your blog if you like — might be of help to someone else.

    Get most recent updated row from the WWV_FLOW_FND_USER table for the user ‘ADMIN’:

    select *
    from APEX_040200.WWV_FLOW_FND_USER
    where user_name = ‘ADMIN’
    order by last_update_date desc;

    Update the WEB_PASSWORD for the row by using the USER_ID and USER_NAME as keys:

    update APEX_040200.WWV_FLOW_FND_USER
    set web_password = ‘My_New_Password’
    where user_name = ‘ADMIN’
    and user_id = 17521141490402; — from SELECT above

    Take care.

  • August 21, 2013 at 4:12 pm

    Hi, everyone,

    First, comment on the post on May 31 about the instruction to ‘Create the Web Archive for Oracle Application Express Images’, the document is correct as i.war is to be created. The following is in page 1-12 of E25066.pdf.

    Use the static command to create a web archive file named i.war:
    java -jar apex.war static \images
    Where is the directory location of Oracle Application Express.

    I have a different problem and don’t know if anyone has tried it and has it working. It is about configuring multiple databases. I tried both methods in page 2-1 of the same document but cannot make it works when deployed in glassfish server. I can see the url-mapping.xml in the temp\apex directory but does not seem to work. Anyone can give some idea? Thx.

  • January 20, 2017 at 7:29 am

    Very clear and structured article..! Do you know if I need to change the database connection… Do I have to reconfigure and redeploy apex.war? or the DB settings are written in an xml file???


  • January 20, 2017 at 9:21 am

    after making changes, you shouldn’t have to redeploy the apex.war file, but you may have to bounce the web server.
    If you are indeed still on version 2 of the listener, I highly recommend upgrading to the latest version.

  • January 20, 2017 at 1:18 pm

    in order to change the database that APEX listener 2 connects to… you need to create a new configdir:
    java -jar apex.war configdir /newconf
    and then rerun:
    java -jar apex.war
    and follow the steps to enter database information.

    So how can glassfish “see” the changes if I do not redeploy apex.war???

    PS. I can not update to the new version … I have apex 4.2 and Database 10g…

Comments are closed.