Oracle APEX：掌握通过JavaScript正确调用应用程序级进程的方法

本教程详细阐述了在oracle APEX中通过JavaScript动态调用应用程序级进程的正确方法。它澄清了apex.submit()与apex.server.process()之间的关键区别，指出前者仅用于页面提交，而后者才是执行命名服务器端进程的ajax首选。文章提供了示例代码和配置指导，帮助开发者高效、异步地触发服务器端逻辑，避免常见的调用误区。

在Oracle APEX应用程序开发中，我们经常需要从客户端（浏览器）触发服务器端的PL/sql逻辑。这通常通过调用“应用程序级进程”或“页面级进程”来实现。然而，许多开发者在尝试使用JavaScript调用这些进程时，可能会遇到一些误区，尤其是在区分apex.submit()和apex.server.process()的功能时。本文将深入探讨这两种方法的差异，并提供如何正确、高效地调用应用程序级进程的专业指南。

理解APEX中的进程调用机制

Oracle APEX提供了两种主要的JavaScript函数来与服务器进行交互，它们各自服务于不同的目的：

apex.submit()：页面提交的核心

apex.submit()函数用于提交整个APEX页面。当调用此函数时，浏览器会将当前页面的所有表单数据发送到服务器。服务器会执行一系列标准的APEX页面生命周期事件，包括：

• 页面计算 (Page Computations)
• 页面验证 (Page Validations)
• 页面处理 (Page Processes)
• 分支 (Branches)

apex.submit()通常用于需要刷新页面、保存数据或执行依赖于整个页面上下文的复杂操作的场景。它可以接受一个包含请求值（request）、显示等待动画（showWait）和执行验证（validate）等选项的JavaScript对象。例如：

立即学习“Java免费学习笔记（深入）”；

apex.submit( {     request: "SAVE_DATA",     showWait: true,     validate: true } );

这里的request: “SAVE_DATA”会将页面的REQUEST项值设置为”SAVE_DATA”。服务器端的页面进程或应用程序进程可以根据这个REQUEST值来决定是否执行。

apex.server.process()：异步服务器交互的利器

apex.server.process()函数则用于执行一个命名的服务器端进程（可以是应用程序级进程或页面级进程），并通过AJAX（异步JavaScript和xml）方式与服务器进行交互。这意味着它不会导致整个页面刷新，而是只在后台与服务器通信。这对于需要执行以下操作的场景非常有用：

• 获取数据而不刷新页面
• 保存数据而不中断用户体验
• 执行后台任务
• 动态更新页面元素

apex.server.process()需要指定要调用的进程的名称，并且可以传递参数，以及定义成功和失败的回调函数。

常见误区：为何apex.submit()无法直接调用命名进程

许多开发者会尝试使用apex.submit()来调用一个应用程序级进程，例如：

// 错误的调用方式示例 apex.submit( {     request: "DOWNLOAD_USER_LIST",     showWait: true,     validate: true } );

并期望一个名为”DOWNLOAD_USER_LIST”的应用程序进程会被直接执行。然而，这种做法通常不会达到预期效果，或者至少不是最直接和高效的方式。

原因在于：

1. apex.submit()触发的是页面生命周期，而不是直接的命名进程调用。 当你使用apex.submit({ request: “DOWNLOAD_USER_LIST” })时，你实际上是告诉APEX：“提交页面，并将REQUEST的值设置为DOWNLOAD_USER_LIST”。服务器在处理这次页面提交时，会检查所有页面进程和应用程序进程的条件。如果有一个进程的条件是Request = DOWNLOAD_USER_LIST，那么它会在页面提交过程中被执行。
2. 期望的异步行为与实际的页面刷新冲突。 如果你期望的是一个后台下载或数据处理，apex.submit()导致的页面刷新可能会中断这个过程，或者使得下载行为变得不直观。例如，如果下载文件需要JavaScript触发，页面刷新可能会阻止该触发。
3. apex.server.process()是为直接、异步调用命名进程而设计的。 它是APEX提供给开发者用于执行服务器端PL/SQL逻辑而不刷新页面的标准和推荐方法。

因此，即使你的应用程序进程条件设置为Request = DOWNLOAD_USER_LIST，并通过apex.submit()触发，虽然理论上该进程可能会在页面提交时运行，但这并非直接调用该命名进程的AJAX方式，且可能与你期望的异步行为相悖。

正确实践：使用apex.server.process()调用应用程序进程

要正确地从客户端JavaScript调用一个应用程序级进程，你应该使用apex.server.process()。

动态操作配置

假设你有一个按钮，点击后需要触发一个文件下载的应用程序级进程。

1. 创建按钮： 在APEX页面上创建一个按钮，例如名为”Download Report”。
2. 创建动态操作：
   • 事件：Click
   • 选择类型：Button
   • 按钮：选择你创建的”Download Report”按钮。
3. 创建真动作：
   • 动作：Execute JavaScript Code
   • 代码：输入以下JavaScript代码。

JavaScript代码示例

以下是调用名为DOWNLOAD_USER_LIST的应用程序进程的示例代码：

apex.server.process(     'DOWNLOAD_USER_LIST', // 应用程序或页面进程的名称     {         // 可选：传递参数到服务器端。这些参数将在PL/SQL进程中通过 apex_application.g_x01, g_x02 等访问         x01: 'some_value',         x02: $v('P1_REPORT_ID') // 例如，从页面项获取值     },     {         // 可选：成功回调函数         success: function(pData) {             // pData 包含服务器端进程返回的数据             // 如果是文件下载，服务器端进程会直接发送文件头，浏览器会自动处理下载             console.log('进程执行成功！', pData);             // 可以在这里处理成功后的页面更新，但对于文件下载，通常不需要         },         // 可选：错误回调函数         Error: function(jqXHR, textStatus, errorThrown) {             console.error('进程执行失败！', textStatus, errorThrown);             apex.message.alert('下载失败，请稍后再试。');         },         // 可选：显示加载动画         showWait: true,         // 可选：等待动画的文本         waitText: '正在生成报告...',         // 可选：请求类型，默认为 POST         dataType: 'JSon' // 如果服务器返回json数据     } );

关键点：

• 第一个参数 ‘DOWNLOAD_USER_LIST’ 必须与你的应用程序进程的名称完全匹配。
• 第二个参数是一个JavaScript对象，用于向服务器端进程传递数据。在PL/SQL进程中，你可以通过apex_application.g_x01、apex_application.g_x02等来访问这些值。
• 第三个参数是一个选项对象，用于配置AJAX请求的行为，包括成功/失败回调、等待动画等。

配置应用程序级进程

为了让apex.server.process()能够成功调用，你的应用程序级进程需要正确配置。

1. 导航到应用程序进程：
   • 在APEX Builder中，进入你的应用程序。
   • 点击“共享组件 (Shared Components)”。
   • 在“逻辑 (Logic)”下，点击“应用程序进程 (Application Processes)”。
2. 创建或编辑进程：
   • 点击“创建 (Create)”或选择现有进程进行编辑。
   • 名称 (Name)： 这是最重要的部分。确保此名称（例如 DOWNLOAD_USER_LIST）与你在apex.server.process()中使用的名称完全一致。
   • 类型 (Type)： 通常选择PL/SQL Code。
   • 执行点 (Point)： 对于apex.server.process()调用的应用程序进程，其执行点通常不重要，因为它是通过名称直接调用的，而不是在页面渲染或提交的特定阶段。
   • 条件 (Condition)： 当使用apex.server.process()通过名称调用时，通常不需要设置Request = Expression 1这样的条件，因为进程是直接通过其名称被目标化的。除非你的PL/SQL代码逻辑依赖于REQUEST项。

PL/SQL实现示例（以文件下载为例）

以下是一个简单的PL/SQL代码示例，用于在应用程序进程中生成并下载csv文件：

-- 应用程序进程名称: DOWNLOAD_USER_LIST -- 类型: PL/SQL Code  DECLARE     l_report_id VARCHAR2(100); BEGIN     -- 从客户端传递的参数中获取值     -- 注意：apex_application.g_x01 对应 JavaScript 中的 x01     l_report_id := apex_application.g_x01;      -- 设置http头，指示浏览器下载文件     OWA_UTIL.MIME_HEADER('text/csv', FALSE);     HTP.P('Content-Disposition: attachment; filename="user_list_' || TO_CHAR(SYSDATE, 'yyYYMMDDHH24MI') || '.csv"');     OWA_UTIL.HTTP_HEADER_CLOSE;      -- 生成CSV内容     HTP.PRN('User ID,Username,Email'); -- CSV头     FOR rec IN (         SELECT user_id, username, email         FROM your_users_table         WHERE report_id = l_report_id -- 示例：根据传入参数过滤     ) LOOP         HTP.PRN(rec.user_id || ',' || rec.username || ',' || rec.email);     END LOOP;  EXCEPTION     WHEN OTHERS THEN         -- 错误处理         HTP.P('Error generating report: ' || SQLERRM);         -- 也可以记录错误到日志表         RAISE; -- 重新抛出异常，让客户端的 error 回调捕获 END;

注意： 对于文件下载，服务器端进程直接输出文件内容和HTTP头。客户端的success回调通常不会收到可处理的数据，因为浏览器会直接处理下载。

注意事项与最佳实践

1. 何时选择apex.submit() vs apex.server.process()：

   • apex.submit()： 当你需要执行完整的页面生命周期，包括验证、计算、页面处理和分支，并且需要刷新页面时使用。
   • apex.server.process()： 当你需要执行特定的服务器端PL/SQL逻辑，但不想刷新页面，并且希望通过AJAX异步处理时使用。这是执行命名应用程序或页面进程的首选方法。

2. 错误处理： 务必在apex.server.process()中包含error回调函数，以便在服务器端进程发生错误时能够及时通知用户或进行日志记录。

3. 安全性考虑： 在服务器端进程中处理任何来自客户端的输入时，务必进行适当的验证和清理，以防止sql注入等安全漏洞。

4. 调试：

   • 对于apex.submit()，可以使用APEX的调试模式来查看页面提交过程中哪些进程被执行以及它们的条件评估结果。
   • 对于apex.server.process()，可以使用浏览器的开发者工具（网络标签页）来检查AJAX请求和响应。同时，在PL/SQL进程中可以使用APEX_DEBUG.MESSAGE来记录调试信息，并在APEX会话中查看。

5. 跨页面的行为一致性： 如果你在其他页面使用apex.submit()成功触发了类似的功能，很可能是因为那些页面上的进程是页面级进程，或者应用程序进程的条件与页面提交的REQUEST值完美匹配，且其逻辑与页面刷新兼容。但即便如此，apex.server.process()仍然是执行独立服务器端逻辑更清晰、更现代的方式。

总结

在Oracle APEX中，理解apex.submit()和apex.server.process()之间的区别对于编写高效且可维护的代码至关重要。apex.submit()用于触发完整的页面提交生命周期，而apex.server.process()则是执行命名服务器端PL/SQL进程的异步（AJAX）首选。通过正确使用apex.server.process()，开发者可以实现更流畅的用户体验，例如在不刷新页面的情况下进行数据处理、文件下载或动态内容更新。始终确保应用程序进程的名称与JavaScript调用中的名称完全匹配，并充分利用回调函数进行错误处理和用户反馈。