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

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

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

ملاحظة: يجب إكمال قسم البدء قبل البدء في هذا القسم.

نقدّم لك AdvancedExampleServlet2

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

يتم وصف الأجزاء الأكثر أهمية في AdvancedExampleServlet2 في الأقسام التالية:

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

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

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

يتجاوز المقتطف التالي doGet(). تتضمّن المعلّمة HttpServletRequest الطلب الذي يتم من خلال التمثيل البصري لخدمة حيثامحة. تتضمن معلمة HttpServletResponse الاستجابة من الخادم التابع لالتمثيل البصري لطلب البحث. يؤدي هذا المقتطف أيضًا إلى ضبط القيمة 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. وبعد ذلك، يُحدّد الرمز استجابة استجابة Selive. تعرض حاوية بحثخة هذه الاستجابة إلى التمثيل البصري لطلب البحث.

      DataSourceHelper.setServletResponse(newData, dsRequest, resp);

الأخطاء المتعلقة بمعالجة البيانات

يحصل المقتطف التالي على استثناء، ويتلقّى الرسالة المناسبة وينسّق الرد ويحدّد استجابة الخادم. وإذا كانت قيمة 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 Catcat. هذه التعليمات مخصّصة لنظام 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 في متصفّح. من المفترض أن يظهر لك ما يلي:
   
   

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

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