XMLDotNet Plugin Documentation

XMLDotNet IRIS plugin

Overview

The xmldotnet plugin for IRIS exposes programming APIs to facilitate sending data to IRIS for harvesting.

Note: main documentation TBD

Harvesting using POJOs

The preferred way to harvest is to build an ontology using POJOs and then send all the data to IRIS. IIrisRemoteXmlConnection provides 2 methods for doing this:

 366         /// <summary>
 367         /// Constructs a new memory POJO factory. A memory POJO factory can be used to
 368         /// create and populate POJOs in memory. The results can then be sent to IRIS.
 369         /// </summary>
 370         /// <returns>The factory which can be used to create and populate POJOs</returns>
 371         /// <see cref="SendUpdateToIRIS"/>
 372         /// <see cref="NewUpdateType"/>
 373         IDotNetMemoryPojoFactory NewMemoryPojoFactory();

The above method creates a factory which allows in-memory POJOs to be constructed.

 383         /// <summary>
 384         /// Sends all updates from a memory POJO factory to IRI.
 385         /// </summary>
 386         /// <param name="factory">The memory POJO facory which contains the updates</param>
 387         /// <param name="kb">The knowledgebase to send updates (can be null)</param>
 388         /// <param name="harvesterUri">The URI of the harvester. This can be any URI provided that
 389         /// it is unique across applications. It can also be the same URI as the PubSub URI used by 
 390         /// the app.</param>
 391         /// <param name="harvestingThreadName">The name of a thread to spawn in IRIS. Applications shouldn't
 392         /// vary this parameter too mush as it will create a lot of unecessarty threads on the IRIS server.
 393         /// </param>
 394         /// <param name="isHighPriority">Whether or not the message is high priotity. In general,
 395         /// messages about user actions are high priority. Messages about harvesting data are usually
 396         /// low priority.</param>
 397         /// <returns>The harvest XML element that was sent</returns>
 398         harvestType SendUpdateToIRIS(IDotNetMemoryPojoFactory factory, String kb, string harvesterUri,
 399             string harvestingThreadName, bool isHighPriority);

The above method sends whatever changes have taken place in the POJO factory to IRIS.

In order to use these methods, the project must contain a reference to "IrisDotNet.dll". Note that the "IrisXml" project already references this DLL and it will be located in the directory iris/plugins/win32/bin/2.0/x86d

For example, consider the case of sending a calendar event to IRIS. GThe following code does this:

200         private void calItemSelectButton_Click(object sender, EventArgs e)
201         {
202             // Use the memory POJO factory
203             // It is important to re-use the factory for performance reasons
204             lock (pojoFactory)
205             {
206                 try
207                 {
208                     buildCalendarSelectOntology();
209                     xmlRemote.SendUpdateToIRIS(pojoFactory, "calkb", APP_URI,
210                                                HARVEST_THREAD_NAME, true);
211                 } finally
212                 {
213                     pojoFactory.clear();
214                 }
215             }
216         }
217 
218         private void buildCalendarSelectOntology()
219         {
220             ICalendarPojo calendar = pojoFactory.createMemoryPojo<ICalendarPojo>();
221             IEventEntryPojo calendarEntry = pojoFactory.createMemoryPojo<IEventEntryPojo>();
222             IPersonPojo userPojo = pojoFactory.createMemoryPojo<IPersonPojo>();
223             // Note: data is canonicalized, so it is not necessary to set first/last name
224             // Note: can also set other info ont he attendees. For example, if there email is know
225             userPojo.setPersonFullNameIs("John Doe");
226             userPojo.setCalendarId("jdoe");
227             calendar.setSourceURIIs("http://test_cal_uri");
228             calendar.setSourceUIDIs("http://test_cal_id");
229             calendar.setCalendarUserIs(userPojo);
230             // Fill out calendar entry details
231             calendarEntry.setSourceUIDIs("http://test_cal_entry_id");
232             calendarEntry.setSourceURIIs("http://test_cal_entry_uri");
233             calendarEntry.setCalendarEntryStartTimeIs(DateTime.Now);
234             calendarEntry.setCalendarEntryEndTimeIs(DateTime.Now.AddHours(2));
235             calendarEntry.setCalendarDescriptionIs("Calendar entry description");
236             calendarEntry.setCalendarEntrySummaryIs("Calendar entry summary");
237             ISubjectCategoryPojo sampleCategory = pojoFactory.createMemoryPojo<ISubjectCategoryPojo>();
238             sampleCategory.setDisplayNameIs("Test category");
239             calendarEntry.addCalendarEntryCategoriesIs(sampleCategory);
240             calendarEntry.setCalendarEntryOrganizerIs(userPojo);
241             IPersonPojo attendee1 = pojoFactory.createMemoryPojo<IPersonPojo>();
242             IPersonPojo attendee2 = pojoFactory.createMemoryPojo<IPersonPojo>();
243             attendee1.setPersonFullNameIs("Jane Doe");
244             attendee2.setPersonFullNameIs("Bob Doe");
245             attendee2.setContactWorkEmail("Robert Doe <bob.doe@sri.com>");
246             calendarEntry.addCalendarEntryAttendeeIs(attendee1);
247             calendarEntry.addCalendarEntryAttendeeIs(attendee2);
248             calendar.add_part(calendarEntry); // add to calendar
249 
250             // Now add the PubSub event. IRIS will automatically detect
251             // ths is present and dispatch it. Note that if this event is
252             // ommitted, IRIS will still  harvest the ontology data above.
253             IExecutionSucceededMessagePojo pubSubMessage = pojoFactory.createMemoryPojo<IExecutionSucceededMessagePojo>();
254             ISelectCalendarEntryPojo selectEvent = pojoFactory.createMemoryPojo<ISelectCalendarEntryPojo>();
255             selectEvent.setCalendarEvent(calendarEntry);
256             selectEvent.setCalendarId(calendarEntry.getSourceUIDIs());
257             pubSubMessage.setTaskIs(selectEvent);
258             pubSubMessage.setSentDateIs(DateTime.Now);
259             pubSubMessage.setSenderIs(APP_URI);
260         }

This code can be run by executing the sample TestApp located at iris/plugins/win32/bin/2.0/x86d/TestXMLApp/TestXMLApp.cs.exe (click Connect and then click the button to send the calendar entry).

In the above example note the following:

The data is sent to "calkb". This database name must be one of the databases already set up in IRIS (see kb.xml).
It is possible to create PubSub events directly and IRIS will auto-detect this and dispatch them. The sender and date should be set on the PubSub message. See the PubSub documentation for more details.
The factory should be re-used for performance reasons. POJO implementations are auto-generated using DynamicProxy and this can take a few seconds the first time. Above the factory is locked while the ontology is built, and cleared in the finally cause of a try statement.
When data is needed it is simply created. For example, the above code creates Person instances when needed. IRIS will properly normalize these instances with the kb.
When creating Person instances it is not necessary to fill out all the fields. If the full name is filled out, IRIS canonicalizes the information and sets the first/last/display names.