المكتبة التقنية ←

الحفاظ على مسودات الجلسة باستخدام Oracle APEX Collections

English version

A multi-step form needs somewhere to hold rows while the user reviews them. My original LinkedIn post introduced APEX Collections for this job. The detail that matters in practice is the draft's lifecycle: creating, revisiting, editing, and finally submitting it.

Treat a collection as temporary APEX-managed session data. Its SQL interface is the database view APEX_COLLECTIONS; do not design around assumptions of purely browser memory or zero database work. Use persistent draft tables when a request must survive beyond its session or be reviewed by another user. Oracle: using collections

Initialize without resetting on refresh

For a development demonstration, add a page process that initializes the following uniquely named collection. The sample uses synthetic products and assumes normal, sequential page requests in an active APEX application session.

begin
    if not apex_collection.collection_exists('DEMO_CART_20261117') then
        apex_collection.create_collection(
            p_collection_name => 'DEMO_CART_20261117'
        );
        apex_collection.add_member(
            p_collection_name => 'DEMO_CART_20261117',
            p_c001 => 'Notebook',
            p_n001 => 2,
            p_n002 => 12.50
        );
        apex_collection.add_member(
            p_collection_name => 'DEMO_CART_20261117',
            p_c001 => 'Pen',
            p_n001 => 3,
            p_n002 => 2
        );
    end if;
end;

COLLECTION_EXISTS checks the current user, session, and application. CREATE_COLLECTION normally raises an error if that collection already exists. This guard preserves the existing draft when the process is visited again. It is not a concurrency lock: coordinate simultaneous initialization requests in your application. Existence check, creation API

Keep an explicit “Start again” action separate from routine rendering. Calling a truncate/reset operation on every render defeats the draft's purpose. Keep initialization separate from an “Add product” action, which needs its own duplicate-submission rules.

Read typed attributes with meaningful aliases

In a Classic Report, use:

select seq_id,
       c001 as product_name,
       n001 as quantity,
       n002 as unit_price,
       n001 * n002 as line_total
from apex_collections
where collection_name = 'DEMO_CART_20261117'
order by seq_id;

The mapping is part of your application contract: C001 means product name, N001 quantity, and N002 unit price. Document it in a small package when several pages share it. Keep numbers in numeric attributes and retain normal text escaping in reports. Oracle documents the typed attributes and collection query pattern. Key concepts

For a newly initialized collection, the expected rows are:

SEQ_ID  PRODUCT_NAME  QUANTITY  UNIT_PRICE  LINE_TOTAL
1       Notebook     2         12.50       25.00
2       Pen          3          2.00        6.00

The total is 31.00; actual decimal formatting follows your report settings. Refreshing the page should retain those two rows rather than append another pair.

Update one attribute without clearing its neighbours

On an explicit development test action, change the first row's quantity:

begin
    apex_collection.update_member_attribute(
        p_collection_name => 'DEMO_CART_20261117',
        p_seq             => 1,
        p_attr_number     => 1,
        p_number_value    => 4
    );
end;

The numeric overload changes N001; the product and unit price remain intact. The expected Notebook line total becomes 50.00 and the overall total 56.00. A missing member raises an error. Numeric attribute update

This differs from UPDATE_MEMBER, which nullifies attributes you do not supply. That distinction can explain why changing a quantity unexpectedly erases a description or price. Member replacement semantics

Define the boundary of the draft

Browser tabs sharing the same application session can reach the same named collection. For independent drafts, use a server-managed draft identifier and consistent ownership checks; a fixed collection name is not a per-tab isolation mechanism.

Do not assume SEQ_ID is a permanent business identifier. Deletion can leave gaps and resequencing can change IDs. For an editable grid, follow Oracle's guidance to store a stable row key in a collection attribute. Sequence behaviour, grid guidance

Before final submission, validate quantity ranges, product access, and current prices on the server. Save accepted data through a deliberate business transaction and clear the temporary draft only after the save succeeds. Test refreshes, two tabs, an expired session, missing rows, and a failed final save. These examples explain expected behaviour; they do not claim execution against an application or measured performance results.

Original LinkedIn post

النسخة العربية

النموذج الذي يتكوّن من عدة خطوات يحتاج مكانًا يحتفظ بالصفوف أثناء مراجعتها. في البوست الأصلي على LinkedIn، عرضت APEX Collections لهذا الاستخدام. التفصيلة المهمة عمليًا هي دورة حياة المسودة: إنشاؤها، والرجوع إليها، وتعديلها، ثم تقديمها نهائيًا.

تعامل مع Collection كبيانات مؤقتة تديرها APEX ضمن الجلسة. واجهة قراءتها بـSQL هي Database View اسمها APEX_COLLECTIONS؛ فلا تبنِ التصميم على افتراض أنها مجرد ذاكرة داخل المتصفح أو أنها لا تستهلك أي عمل في قاعدة البيانات. استخدم جداول مسودات دائمة لو الطلب لازم يستمر بعد الجلسة أو يراجعه مستخدم آخر. Oracle: استخدام Collections

ابدأ المسودة بدون تصفيرها عند التحديث

في مثال للتطوير، أضف Page Process لإنشاء Collection بالاسم المميز التالي. المثال يستخدم منتجات افتراضية، ويفترض طلبات صفحات متتابعة بشكل عادي داخل جلسة تطبيق APEX فعّالة.

begin
    if not apex_collection.collection_exists('DEMO_CART_20261117') then
        apex_collection.create_collection(
            p_collection_name => 'DEMO_CART_20261117'
        );
        apex_collection.add_member(
            p_collection_name => 'DEMO_CART_20261117',
            p_c001 => 'Notebook',
            p_n001 => 2,
            p_n002 => 12.50
        );
        apex_collection.add_member(
            p_collection_name => 'DEMO_CART_20261117',
            p_c001 => 'Pen',
            p_n001 => 3,
            p_n002 => 2
        );
    end if;
end;

تفحص COLLECTION_EXISTS المستخدم والجلسة والتطبيق الحاليين. وCREATE_COLLECTION ترفع خطأ عادةً لو نفس الـCollection موجودة بالفعل. الشرط بيحافظ على المسودة الموجودة عند زيارة العملية مرة ثانية. لكنه مش قفل للتزامن: نسّق طلبات الإنشاء المتزامنة داخل التطبيق. فحص الوجود، توثيق الإنشاء

افصل إجراء «ابدأ من جديد» عن عرض الصفحة العادي. استدعاء عملية تصفير أو تفريغ عند كل عرض للصفحة بيضيّع الغرض من المسودة. وافصل الإنشاء الأولي عن إجراء «أضف منتجًا»، الذي يحتاج قواعد مستقلة لمنع تكرار التقديم.

اقرأ الأعمدة بأنواعها وأسماء واضحة

في Classic Report، استخدم:

select seq_id,
       c001 as product_name,
       n001 as quantity,
       n002 as unit_price,
       n001 * n002 as line_total
from apex_collections
where collection_name = 'DEMO_CART_20261117'
order by seq_id;

معنى الأعمدة جزء من عقد التطبيق: C001 اسم المنتج، وN001 الكمية، وN002 سعر الوحدة. وثّق الربط في Package صغيرة عندما تتشارك فيه عدة صفحات. احتفظ بالأرقام في الأعمدة الرقمية، وبالحماية المعتادة للنصوص عند عرض التقارير. توثّق Oracle أنواع الأعمدة ونمط قراءة Collection. المفاهيم الأساسية

عند إنشاء Collection جديدة، الصفوف المتوقعة هي:

SEQ_ID  PRODUCT_NAME  QUANTITY  UNIT_PRICE  LINE_TOTAL
1       Notebook     2         12.50       25.00
2       Pen          3          2.00        6.00

الإجمالي 31.00؛ والتنسيق الفعلي للفواصل والأرقام يتبع إعدادات التقرير. تحديث الصفحة المفروض يحتفظ بالصفّين بدل إضافة نسخة ثانية منهما.

عدّل قيمة واحدة بدون مسح القيم المجاورة

في إجراء اختبار صريح داخل بيئة التطوير، غيّر كمية الصف الأول:

begin
    apex_collection.update_member_attribute(
        p_collection_name => 'DEMO_CART_20261117',
        p_seq             => 1,
        p_attr_number     => 1,
        p_number_value    => 4
    );
end;

النسخة الرقمية من الدالة الإجرائية بتعدّل N001، بينما اسم المنتج وسعر الوحدة يفضلوا كما هم. إجمالي Notebook المتوقع يصبح 50.00، والإجمالي العام 56.00. ولو العضو المطلوب غير موجود يحصل خطأ. تعديل العمود الرقمي

ده مختلف عن UPDATE_MEMBER التي تضع NULL في الأعمدة التي لم ترسل قيمها. الفرق ده ممكن يفسّر ليه تعديل الكمية أحيانًا يمسح الوصف أو السعر بدون قصد. سلوك استبدال العضو

حدّد حدود المسودة

تبويبات المتصفح التي تتشارك نفس جلسة التطبيق يمكنها الوصول لنفس Collection المسماة. للمسودات المستقلة، استخدم معرّف مسودة يديره السيرفر مع تحقق ثابت من الملكية؛ اسم Collection ثابت مش وسيلة لعزل كل تبويب لوحده.

ما تعتبرش SEQ_ID معرّف عمل دائمًا. الحذف ممكن يترك فجوات، وإعادة الترقيم ممكن تغيّر الأرقام. وفي Editable Grid، اتبع إرشاد Oracle بتخزين مفتاح صف ثابت في أحد أعمدة Collection. سلوك الترقيم، إرشاد الـGrid

قبل التقديم النهائي، تحقّق على السيرفر من نطاق الكمية وصلاحية الوصول للمنتجات والأسعار الحالية. احفظ البيانات المقبولة من خلال معاملة عمل واضحة، ولا تفرّغ المسودة المؤقتة إلا بعد نجاح الحفظ. اختبر تحديث الصفحة، وتبويبين، وانتهاء الجلسة، والصفوف المفقودة، وفشل الحفظ النهائي. الأمثلة بتشرح السلوك المتوقع، ولا تدّعي تنفيذًا على تطبيق أو نتائج أداء مقاسة.

البوست الأصلي على LinkedIn