cnelson

Event Frame Search Method Changes in AF-SDK 2.4

Blog Post created by cnelson Employee on Aug 29, 2011

 

 

Hello Community!!!

 

 

 

First, let me apologize for my lack of blogging since my original post in 2009!  I had high hopes of monthly posts, but that faded away as the Event Frame work load grew :)

 

 

 

Second, thanks for your excellent feedback, ideas, and thoughts around Event Frames.  As I have said at the numerous conferences and events I presented at - we may not always get back to you but we in Engineering are all reading and listening to the conversations.  You have greatly aided us in focusing our attention in the right places to get the features that you need.

 

 

 

Last before we get to the subject matter, I hope you all have been monitoring the Product Roadmap and are anticipating the upcoming release of PI AF 2010 R3 which will officially release PI Event Frames.  Leading up to this release, I will be blogging on several topics that you need to be aware of.  This first post is by far the most important because we have changed some behavior in the AF-SDK in relation to Event Frames based on internal design reviews. 

 

 

 

This will be the summary of this post that you need to take away:

 

 

 

IF YOU HAVE BUILT AN APPLICATION AGAINST THE AF-SDK 2.3 OR BELOW THAT USES ANY OF THE AFEVENTFRAME.FIND… METHODS, YOU WILL NEED TO RECOMPILE YOUR APPLICATION AGAINST THE AF-SDK 2.4.

 

 

 

The rest of this post goes into details on why we made these changes and what these changes are.

 

 

 

In AF2.3, we added paged searches for Event Frames so we added additional method signatures.  Including the FindEventFramesbyAttribute method, this caused the number of find methods to go from 4 to 8. 

 

 

 

During the design process, the team has always been frustrated by the number of overloads because it limits the usefulness of intellisense and confuses the programmer. 

 

 

 

In AF 2.3 we have the following list of searches:

 

FindEventFrames(AFDatabase, AFEventFrame, String, AFSearchField, Boolean, AFSortField, AFSortOrder, Int32)

Performs a search within the AFDatabase to retrieve a non-paged collection of AFEventFrame objects that match the specified query string.

FindEventFrames(AFDatabase, AFEventFrame, Object, Int32, Boolean, String, String, AFCategory, AFElementTemplate, Boolean)

Retrieves a non-paged list of AFEventFrame objects limited to the specified count beginning at the requested start time in the specified direction.

FindEventFrames(AFDatabase, AFEventFrame, String, AFSearchField, Boolean, AFSortField, AFSortOrder, Int32, Int32, Int32)

Performs a search within the AFDatabase to retrieve a paged collection of AFEventFrame objects that match the specified query string.

FindEventFrames(AFDatabase, AFEventFrame, Object, Int32, Int32, Boolean, String, String, AFCategory, AFElementTemplate, Boolean, Int32)

Retrieves a paged list of AFEventFrame objects limited to the specified count beginning at the requested start time in the specified direction.

FindEventFrames(AFDatabase, AFEventFrame, AFSearchMode, Object, Object, String, String, AFCategory, AFElementTemplate, AFDurationQuery[], Boolean, AFSortField, AFSortOrder, Int32)

Retrieves a non-paged list of AFEventFrame objects that match the specified filtering conditions.

FindEventFrames(AFDatabase, AFEventFrame, AFSearchMode, Object, Object, String, String, AFCategory, AFElementTemplate, AFDurationQuery[], Boolean, AFSortField, AFSortOrder, Int32, Int32, Int32)

Retrieves a paged list of AFEventFrame objects that match the specified filtering conditions.

FindEventFramesByAttribute(AFEventFrame, AFSearchMode, Object, Object, String, String, AFDurationQuery[], AFAttributeValueQuery[], Boolean, AFSortField, AFSortOrder, Int32)

Performs a search on the event frame's name and attribute value within the AFDatabase to retrieve a non-paged collection of AFEventFrame objects.

FindEventFramesByAttribute(AFEventFrame, AFSearchMode, Object, Object, String, String, AFDurationQuery[], AFAttributeValueQuery[], Boolean, AFSortField, AFSortOrder, Int32, Int32, Int32)

Performs a search on the event frame's name and attribute value within the AFDatabase to retrieve a paged collection of AFEventFrame objects.

 

 

In AF2.4, we have made two changes.  First, to support an enhancement request of searching backward and forward using the end date, we added a new method and obsoleted two related methods.  This new method takes an enumeration, AFEventFrameSearchMode which has four settings:

 

Member name

Value

Description

None

0

This is the value of an uninitialized search mode.

BackwardFromStartTime

1

Event frames less than or equal to the start time (moving backward in time) are returned from the search.

ForwardFromStartTime

2

Event frames greater than or equal to the start time (moving forward in time) are returned from the search.

BackwardFromEndTime

3

Event frames less than or equal to the end time (moving backward in time) are returned from the search.

ForwardFromEndTime

4

Event frames greater than or equal to the end time (moving forward in time) are returned from the search.

 

 

Below is the list of new methods for AF2.4 relating to these Event Frame Search methods.  We have decided to remove the Obsoleted methods in AF2.4.

 

Name

Description

FindEventFrames(AFDatabase, AFEventFrame, Object, Int32, AFEventFrameSearchMode, String, String, AFCategory, AFElementTemplate, Boolean)

New Method using AFEventFrameSearchMode

Retrieves a non-paged list of AFEventFrame objects limited to the specified count beginning at the requested time in the specified direction.

FindEventFrames(AFDatabase, AFEventFrame, Object, Int32, Boolean, String, String, AFCategory, AFElementTemplate, Boolean)

Obsolete.

Retrieves a non-paged list of AFEventFrame objects limited to the specified count beginning at the requested start time in the specified direction.

FindEventFrames(AFDatabase, AFEventFrame, Object, Int32, Int32, AFEventFrameSearchMode, String, String, AFCategory, AFElementTemplate, Boolean, Int32)

New Method using AFEventFrameSearchMode

Retrieves a paged list of AFEventFrame objects limited to the specified count beginning at the requested time in the specified direction.

FindEventFrames(AFDatabase, AFEventFrame, Object, Int32, Int32, Boolean, String, String, AFCategory, AFElementTemplate, Boolean, Int32)

Obsolete.

Retrieves a paged list of AFEventFrame objects limited to the specified count beginning at the requested start time in the specified direction.

 

 

The second and biggest change occurred on how we implemented paged searches for Event Frames.  After several internal design reviews, the team came to the conclusion that the original design that included passing back the TotalCount was counter productive to why we implemented paging in the first place, to increase performance and scalability. 

 

 

 

Including the total count is very expensive because it requires processing the entire history of event frames, which grows over time.  Because of this, we decided to remove the TotalCount output parameter.  When doing this, we realized we had an opportunity to reduce the # of overrides which is very confusing to the programmer.  So, currently we decided to change the method signatures for AF2.4 from 8 back down to 4 to reduce complexity.

 

 

 

In AF 2.4 we have the following list of searches:

 

Name

Description

FindEventFrames(AFDatabase, AFEventFrame, String, AFSearchField, Boolean, AFSortField, AFSortOrder, Int32, Int32)

Performs a search within the AFDatabase to retrieve a paged collection of AFEventFrame objects that match the specified query string.

FindEventFrames(AFDatabase, AFEventFrame, Object, Int32, Int32, AFEventFrameSearchMode, String, String, AFCategory, AFElementTemplate, Boolean)

Retrieves a paged list of AFEventFrame objects limited to the specified count beginning at the requested time in the specified direction.

FindEventFrames(AFDatabase, AFEventFrame, AFSearchMode, Object, Object, String, String, AFCategory, AFElementTemplate, AFDurationQuery[], Boolean, AFSortField, AFSortOrder, Int32, Int32)

Retrieves a paged list of AFEventFrame objects that match the specified filtering conditions.

FindEventFramesByAttribute

Performs a search on the event frame's name and attribute value within the AFDatabase to retrieve a paged collection of AFEventFrame objects.

 

 

So, the biggest ramification is that you will need to change your application code to reflect these new method signatures.  We are removing the old ones in order to start with a clean slate.  So your application code will not be compatible with AF2.4 unless these changes are made.

 

 

 

The design pattern that we implemented is applicable for paged and non-paged searches, basically all searches are paged depending on the pagesize.  All Find Methods now have two parameters that control the behavior of paging, startIndex and maxcount.  All initial searches should use 0 (zero) as the startindex and maxcount should be equal to requested pagesize.  Realize that performance is directly impacted by the size of your return set which is controlled by the maxcount parameter. 

 

 

 

If the count of your return set equals the maxcount parameter, there is most likely more results that need to be retrieved.  To get these additional results, you must make a subsequent call setting the startindex equal to the previous startindex plus maxcount.

 

 

 

So, in summary, just to be perfectly clear, PI AF2.4 will be the first production version of PI Event Frames.  If you have written applications against the CTP versions of PI AF that include Event Frame features and functions you will need to upgrade them to use PI AF2.4.  So please let me end with my overblown bold statement:

 

 

 

IF YOU HAVE BUILT AN APPLICATION AGAINST THE AF-SDK 2.3 OR BELOW THAT USES ANY PI EVENT FRAME FEATURES, YOU WILL NEED TO RECOMPILE YOUR APPLICATION AGAINST THE AF-SDK 2.4.

 

 

 

We are getting real close!!!!!!!!

 

 

 

 

 

 

Outcomes