تعريف الإمكانات وتدفق الأحداث

يتناول هذا القسم AdvancedExampleServlet2. AdvancedExampleServlet2 هو مثال على تنفيذ مصدر بيانات يحدّد الإمكانات وتدفق الأحداث. يوفّر هذا القسم أيضًا تعليمات مفصّلة حول كيفية تشغيل واختبار AdvancedExampleServlet2.

• نقدّم لك "AdvancedExampleServlet2"
• تشغيل واختبار AdvancedExampleServlet2

ملاحظة: يجب عليك إكمال قسم البدء قبل أن تبدأ هذا القسم.

نقدّم لك "AdvancedExampleServlet2"

تقع الفئة AdvancedExampleServlet2 في الحزمة examples. تقدم هذه الفئة مثالاً على التنفيذ الذي يحدد الإمكانات وتدفق الأحداث.

تم توضيح أهم أجزاء AdvancedExampleServlet2 في الأقسام التالية:

• تحديد تدفُّق الأحداث
• الأخطاء في المعالجة
• استخدام مَعلمات عناوين URL
• استخدام الإمكانات

تحديد تدفُّق الأحداث

تحدّد السمة AdvancedExampleServlet2 تدفّق الأحداث من خلال إلغاء الطريقة HttpServlet.doGet() واستدعاء دوال مساعِدة مختلفة يوفّرها DataSourceHelper.

يلغي المقتطف التالي doGet(). تتضمن المعلمة HttpServletRequest الطلب الذي تم تقديمه من خلال التصور في serlet. تضم المعلمة HttpServletResponse الاستجابة من serlet إلى التصور الخاص بالاستعلام. يؤدي هذا المقتطف أيضًا إلى ضبط السمة dsRequest على قيمة "خالية". يُستخدم dsRequest في نقاط مختلفة في باقي التعليمات البرمجية.

  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    DataSourceRequest dsRequest = null;

يستخرج المقتطف التالي معلَمات الطلب من HttpServletRequest لإنشاء سياق يتم فيه تنفيذ الطلب.

    try {
      // Extract the request parameters.
      dsRequest = new DataSourceRequest(req);

ينقل المقتطف التالي الطلب من الكائن dsRequest و يقسّمه إلى طلبَي بحث منفصلَين. يسمى أحد الاستعلامات استعلام مصدر البيانات، والآخر استعلام الإكمال. بما أنّ السمة المُعلَن عنها من مصدر البيانات هي SELECT، يتألف طلب بحث مصدر البيانات من عملية SELECT إذا كان الهدف dsRequest يتضمّن عملية SELECT. يتألف استعلام الإكمال من جميع العمليات الأخرى التي يتطلبها الطلب، والتي قد تتضمّن أيضًا عملية SELECT. على سبيل المثال، إذا كان طلب البحث المطلوب هو SELECT a ORDER BY b، سيكون طلب البحث عن مصدر البيانات هو SELECT a, b وسيكون طلب البحث لإكمال العملية هو نفسه طلب البحث الأصلي SELECT a ORDER BY b.

      // Split the query.
      QueryPair query = DataSourceHelper.splitQuery(dsRequest.getQuery(), Capabilities.SELECT);

يأخذ المقتطف التالي استعلام مصدر البيانات الذي تم إنشاؤه من خلال المقتطف السابق وHttpServletRequest, وينشئ جدول بيانات. راجِع قسم استخدام الإمكانيات لمزيد من التفاصيل.

      // Generate the data table.
      DataTable data = generateMyDataTable(query.getDataSourceQuery(), req);

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

      // Apply the completion query to the data table.
      DataTable newData = DataSourceHelper.applyQuery(query.getCompletionQuery(), data,
          dsRequest.getUserLocale());

يأخذ الرمز التالي جدول البيانات الذي أنشأه المقتطف السابق، ومعلمات الطلب من HttpServletRequest. يحدد الكود بعد ذلك استجابة serlet. ترجع حاوية serlet هذه الاستجابة إلى تصور الاستعلام.

      DataSourceHelper.setServletResponse(newData, dsRequest, resp);

أخطاء المعالجة

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

    catch (RuntimeException rte) {
      log.error("A runtime exception has occured", rte);
      ResponseStatus status = new ResponseStatus(StatusType.ERROR, ReasonType.INTERNAL_ERROR,
          rte.getMessage());
      if (dsRequest == null) {
        dsRequest = DataSourceRequest.getDefaultDataSourceRequest(req);
      }
      DataSourceHelper.setServletErrorResponse(status, dsRequest, resp);
    } catch (DataSourceException e) {
      if (dsRequest != null) {
        DataSourceHelper.setServletErrorResponse(e, dsRequest, resp);
      } else {
        DataSourceHelper.setServletErrorResponse(e, req, resp);
      }
    }

استخدام مَعلمات عناوين URL

يأخذ المقتطف التالي استعلام مصدر البيانات الذي تم إنشاؤه عند تقسيم طلب البحث وHttpServletRequest. ويمكن أن تتضمّن HttpServletRequest بشكل اختياري مَعلمة tableId محدّدة كعنوان URL. تحدِّد معلمة tableId هذه جدول البيانات الذي يتم عرضه على النحو التالي:

• إذا تم حذف المعلمة tableId أو كانت أي قيمة أخرى غير planets، يعرض مصدر البيانات جدول بيانات الحيوانات.
• إذا تم تحديد المعلمة tableId على أنها planets، يعرض مصدر البيانات جدول بيانات الكواكب.

عندما تكتب التعليمة البرمجية الخاصة بك لإرجاع جدول بيانات، فإنك تقرر المعلمات التي يجب أخذها.

  private DataTable generateMyDataTable(Query query, HttpServletRequest req)
      throws TypeMismatchException {
    String tableID = req.getParameter("tableId");
    if ((tableID != null) && (tableID.equalsIgnoreCase("planets"))) {
      return generatePlanetsTable(query);
    }
    return generateAnimalsTable(query);
  }

استخدام الإمكانات

يأخذ المقتطف التالي طلب البحث وينشئ جدول بيانات animals.

private DataTable generateAnimalsTable(Query query) throws TypeMismatchException {
  DataTable data = new DataTable();
  List requiredColumns = getRequiredColumns(query,
      ANIMAL_TABLE_COLUMNS);
  data.addColumns(requiredColumns);

  // Populate the data table
  for (String key : animalLinksByName.keySet()) {
    TableRow row = new TableRow();
    for (ColumnDescription selectionColumn : requiredColumns) {
      String columnName = selectionColumn.getId();
      if (columnName.equals(ANIMAL_COLUMN)) {
        row.addCell(key);
      } else if (columnName.equals(ARTICLE_COLUMN)) {
        row.addCell(animalLinksByName.get(key));
      }
    }
    data.addRow(row);
  }
  return data;
}

يأخذ المقتطف التالي طلب البحث وينشئ جدول بيانات planets.

private DataTable generatePlanetsTable(Query query) throws TypeMismatchException {
  DataTable data = new DataTable();
  List requiredColumns = getRequiredColumns(
      query, planetTableColumns);
  data.addColumns(requiredColumns);

  // Populate data table
  for (Planet planet : Planet.values()) {
    TableRow row = new TableRow();
    for (ColumnDescription selectionColumn : requiredColumns) {
      String columnName = selectionColumn.getId();
      if (columnName.equals(PLANET_COLUMN)) {
        row.addCell(planet.name());
      } else if (columnName.equals(MASS_COLUMN)) {
        row.addCell(planet.getMass());
      } else if (columnName.equals(GRAVITY_COLUMN)) {
        row.addCell(planet.getSurfaceGravity());
      } else if (columnName.equals(MOONS_COLUMN)) {
        row.addCell(planet.getNumberOfMoons());
      }
    }
    data.addRow(row);
  }
  return data;
}

التشغيل والاختبار AdvancedExampleServlet2

يقدّم هذا القسم تعليمات حول كيفية تشغيل واختبار "AdvancedExampleServlet2".

من أجل تشغيل واختبار AdvancedExampleServlet2، عليك تحديث تطبيق الويب وإعداد عرض مرئي للاستعلام عن مصدر البيانات، كما هو موضّح في الأقسام التالية:

• تحديث تطبيق ويب على Apache Tomcat
• استخدام التمثيل البصري لعرض البيانات

تحديث تطبيق ويب على Apache Tomcat

اتبع التعليمات التالية أو اضبطها لتحديث تطبيق الويب على Apache Tomcat. هذه التعليمات خاصة ببرنامج Apache Tomcat على نظام التشغيل Windows:

1. إنّ الملف web.xml الذي نسخته سابقًا إلى الدليل WEB-INF يحتوي حاليًا على التعريف والربط المطلوبَين لهذا المثال. الأسطر التي تحدد هذه القيم هي:
   
   

   <servlet>
     <servlet-name>AdvancedExampleServlet2</servlet-name>
     <description>
     AdvancedExampleServlet2
     </description>
     <servlet-class>AdvancedExampleServlet2</servlet-class>
   </servlet>
     
   <servlet-mapping>
     <servlet-name>AdvancedExampleServlet2</servlet-name>
     <url-pattern>/advanced</url-pattern>
   </servlet-mapping> 

2. ابدأ تشغيل Tomcat أو أعِد تشغيل Tomcat إذا كان قيد التشغيل.
   
3. انقر على الرابط التالي:http://localhost:8080/myWebApp/advanced
   تعرض الشاشة من 6 إلى 7 أسطر من النص، حسب عرض الشاشة. يبدأ النص بـ google.visualization.Query.setResponse وينتهي بـ {v:'http://en.wikipedia.org/wiki/Tiger'}]}]}});
   هذه هي الإجابة التي يرسلها مثال مصدر بيانات ملف CSV إلى العرض المرئي.

استخدام التمثيل المرئي لعرض البيانات

ويمكن استخدام ملف all_examples.html في الدليل <data_source_library_install>/examples/src/html لعرض مرئيات للبيانات.

يحدد المقتطف التالي من all_examples خادم advanced، وجدول planets، وطلب بحث محدد، ومؤثر عرض مرئي للمخطط الشريطي.

query = new google.visualization.Query('advanced?tableId=planets&tq=select planet,mass');
...
var chart = new google.visualization.BarChart(document.getElementById('advanced_div'));

للحصول على شرح عن الرسوم البيانية الأخرى المضمَّنة في all_examples.html، يُرجى الاطّلاع على القسم استخدام مخزن بيانات خارجي.

لمزيد من المعلومات حول كيفية تحديد تمثيل بصري واستخدام لغة طلب البحث، راجِع استخدام الرسوم البيانية ومرجع لغة طلب البحث.

اتبع أو تكييف التعليمات أدناه لعرض تصور للبيانات التي يقدمها مصدر البيانات المتقدم:

1. إذا لم يسبق لك إجراء ذلك، انسخ ملف all_examples.html من الدليل <data_source_library_install>/examples/src/html
   إلى دليل <tomcat_home>/webapps/myWebApp/.
    
2. انقر على الرابط التالي: http://localhost:8080/myWebApp/all_examples.html في المتصفح. من المفترض أن يظهر لك ما يلي:
   
   

الخطوات التالية

لاستكشاف الأمثلة المتوفّرة مع المكتبة بشكل أكبر، يمكنك الاطّلاع على أمثلة مرجع سريع. لمعرفة المزيد من المعلومات حول استخدام مصدر بيانات معقّد، يمكنك الاطّلاع على نصائح حول التنفيذ.