Paresh Suthar: Groove Programming Tips & Tricks

Sat, 15 Feb 2003 14:43:01 GMT

Release objects cached in GrooveRunTimeData when they are no longer needed

You can either call the RemoveItem method (to remove one item at a time) or you can call the RemoveAllItems method to accomplish this.

Mon, 04 Nov 2002 12:59:21 GMT

Implement COM objects in script

Among the variety of powerful things that Groove's ScriptFreeThreaded component can do, one of the more interesting ones is the ability to implement CoCreate'able objects in script. The Groove Platform GDK contains a sample called YourApp10 that shows how to do this, so I will just summarize the main points. Note that if you don't know much about COM or writing IDL, go get this book and read it.

Write IDL for the COM object
To be a good citizen to early and late binding clients, you should define dual interfaces for non-event interfaces. You should also have 2 flavors of event interfaces, 1 for early bound clients that derives from IUnknown and 1 for late bound clients that is a dispinterface. You should also define a CoClass to publish the interfaces implemented by the COM object. Note that [in, out] and [out] parameters are not supported for methods.

Define OSD so that the COM object can be CoCreate'd
<SOFTPKG NAME="com.yourcompany.xxx.YourCOMObject_GSL" VERSION="1,0,0,0">
   <IMPLEMENTATION>
      <CODEBASE HREF="http://components.yourcompany.com/xxx/YourCOMObject.gsl"/>
      <g:Install Type="Import To XSS" DatabaseURI="$TEMPLATESURI$" DocumentName="YourCOMObject.gsl" SchemaURI="$DEFAULTSCHEMA$"/>
     <g:Factory Name="Open" Type="XML Document" DatabaseURI="$TEMPLATESURI$" DocumentName="YourCOMObject.gsl"/>

     <g:Registry Command="Add" Hive="HKCR" Key="clsid\{FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF}" Value="" Data="Your COM Object" Type="String"/>
     <g:Registry Command="Add" Hive="HKCR" Key="clsid\{FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF}\InprocServer32" Value="" Data="$GROOVEBIN$\GrooveCommonComponents.dll" Type="String"/>
     <g:Registry Command="Add" Hive="HKCR" Key="clsid\{FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF}\InprocServer32" Value="ThreadingModel" Data="Both" Type="String"/>
     <g:Registry Command="Add" Hive="HKCR" Key="clsid\{FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF}\URL" Value="" Data="http://components.yourcompany.com/xxx/YourCOMObject.osd?Package=com.yourcompany.xxx.YourCOMObject_GSL&;amp;Version=1,0&Factory=Open" Type="String"/>
     <g:Registry Command="Add" Hive="HKCR" Key="YourCOMObjects.YourCOMObjectProgID\CLSID" Value="" Data="{FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF}" Type="String"/>
    </IMPLEMENTATION>
</SOFTPKG>

Create a .gsl file for the COM object
This script file should import the type library for your COM object, as well as any other dependent type libraries. You import type libraries by having the following statement:

<TYPELIB LIBID="{FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFE}" NAME="YourCOMObjectTypeLibrary" MAJORVER="1" MINORVER="0"/>

Your script file should implement the interfaces as described by the coclass (at least). You implement interfaces by having the following statement:

<IMPLEMENTS Default="1" IID="{FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF}" LIBID="{FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFE}">

Note that the Default attribute should only be used for one of the implemented interfaces, and omitted from all other implemented interface. Also note that to return HRESULT values, you should use the SetCurrentError method.

Global & instance data storage
You should not define/use global variables because of performance reasons and the fact that they are not thread safe/accessible. Instead you should use GrooveRunTimeData and/or ScriptSharedObjectTables.

Fri, 27 Sep 2002 13:50:03 GMT

Don't use JavaScript classes/objects for storage in ScriptFreeThreadedComponents

Any objects that are allocated by calling the "new" operator have thread affinity - this means that if the thread 1 creates an instance of a JavaScript class, only thread 1 can access/use it. Instead use shared object tables for scalar types or COM objects implemented in script when instance method invocation is required.

Thu, 12 Sep 2002 13:50:12 GMT

Return HRESULTs from script languages that implement COM interfaces

Groove's script host provides an object called GrooveErrorFunctions that you can use call the SetCurrentError method with an HRESULT value and string description. The effect is that an exception is thrown to the caller with the value/description, so the caller should have exception handling code around the method call.

Example
function FindPerson
      (
      i_FirstName,
      i_LastName
      )
   {
   if (i_FirstName == "")
      {
      //   Return E_INVALIDARG (hex value = 0x80000003, integral value = -2147024809)
      GrooveErrorFunctions.SetCurrentError(-2147024809, "First name required!");
      return;
      }

   if (i_LastName == "")
      {
      //   Return E_INVALIDARG (hex value = 0x80000003, integral value = -2147024809)
      GrooveErrorFunctions.SetCurrentError(-2147024809, "Last name required!");
      return;
      }

   var Person = null;

   try
      {
      //   Some code here to find person
      }
   catch (e)
      {
      //   Return E_FAIL (hex value = 0x80004005, integral value = -2147467259)
      GrooveErrorFunctions.SetCurrentError(-2147467259, "Unexpected error!");
      return;
      }

   return Person;
   }

Mon, 09 Sep 2002 13:25:32 GMT

Use globals in script sparingly, as it affects performance

Whenever a variable is referenced in script code, the context of the variable is determined first, which means some sort of lookup. The use of a local variable reduces the surface area of the the lookup to the current function/method, while a global variable has the surface area of the entire CDATA section.

The following list of ways to store global data is prioritized, with the first item being the most performant and the last item being the least performant:

GrooveRunTimeData (ScriptFreeThreadedComponent only)
SharedObjectTable
Global variables

Thu, 05 Sep 2002 13:56:00 GMT

Use the existence of properties/attributes as a boolean value rather than the actual value.

Instead of writing code like this:

   PropertyList.SetProperty("Initialized", true);
   .
   .
   var Initialized = false;
   if (PropertyList.PropertyExists("Initialized"))
      Initialized = PropertyList.OpenValue("Initialized");
   .
   .

Write code like this:

   PropertyList.SetProperty("Initialized", true);
   .
   .
   var Initialized = PropertyList.PropertyExists("Initialized");
   .
   .

Tue, 27 Aug 2002 14:41:23 GMT

Watch out for redundant event subscriptions when using Groove's ScriptHost components

If you define a component connection for Groove's ScriptHost components, the events provided by the component are automatically subscribed to:

   <g:ComponentConnections>
      <g:Connection ConnectionID="0" Name="MyDataModelDelegate"/>
   </g:ComponentConnections>

In the case above, event handlers can be implemented in JavaScript by defining functions that use "MyDataModelDelegate_" as a prefix (e.g. "function MyDataModelDelegate_OnSomeEvent").

If you have JavaScript code defined in the code block that attempts to manually subscribe for events using the ConnectObject/Advise method, you will be providing the prefix for defining functions.

   function Initialize ()
      {
      var pITool = PropertyList.OpenProperty(PROPERTY_TOOL);
      var pIDelegateComponent = pITool.OpenDelegateComponent();
      var pIMyDataModelDelegate = pIDelegateComponent.IMyDataModelDelegate;
      ConnectObject(pIMyDataModelDelegate, "pIMyDataModelDelegate_", true);
      }

In the case above, event handlers can be implemented in JavaScript by defining functions that use "pIMyDataModelDelegate_" as a prefix (e.g. "function pIMyDataModelDelegate_OnSomeEvent").

The problem to watch out for is when you have both a component connection and code that manually subscribes for events from the same component - the ScriptHost component will always perform component connection based event subscriptions first. Additionally, any subsequent attempts to subscribe for events will not actually do anything, and no errors or warnings will be given. What this means is that if you only define an event handler for the manual subscription, those events will never get triggered.

Mon, 26 Aug 2002 13:47:11 GMT

Use Javascript and the "My Templates" directory to rapidly prototype

When you are developing tools that use Groove's UI components, there is no faster way to prototype than by using the "My Templates" directory. What makes it so productive is that any properly formed .tpl file that is placed into this directory (e.g. "c:\program files\groove networks\groove\data\my templates") can immediately be added to a space. Additionally, any changes made to the .tpl file will immediately be seen upon add a new instance of the tool to the space (vs. having to overlay templates using something like Groove Database Navigator).

This technique only works for .tpl files, it will not work for .gsl or .xml files. One thing to keep in mind is that if you need to modify a .tpl file that has dependencies on .gsl or .xml files, once the tool has been injected (via .grv file), you can copy the .tpl file to the "My Templates" directory and use it for rapid prototyping - just make sure to copy the changes back to the original .tpl file.

For more information, check out the Groove Platform GDK documentation.

Fri, 23 Aug 2002 12:50:13 GMT

Use Groove tracing to help debug tools

The Groove platform GDK ships with the Groove Trace Window which is an application that can be used to have information logged/displayed while debugging a tool. Using the tracing facilities is pretty simple:

var pIGrooveTraceControl =
GrooveScriptFunctions.CreateNewObject("GrooveTraceControlLib.GrooveTraceControl");
pIGrooveTraceControl.SendToTraceWindow("This is a test!");

If the Groove Trace Window is not open/running, then any SendToTraceWindow method calls result in nothing being done (i.e. not a performance hit). Once the Groove Trace Window is opened, then all calls to the SendToTraceWindow method call will produce output and it will be serialized. Obviously this is a debugging aid, and all references to it should be removed prior to releasing your tool.

Thu, 22 Aug 2002 13:48:49 GMT

Hold a strong reference to the tool and/or telespace, not just the data model delegate(DMD)

When writing tools that subscribe to DMD events provided by other tools in the same telespace, you (currently) must hold a strong reference to the tool in which the DMD lives to ensure that the tool does not get unloaded.

When writing tools that subscribe to DMD events provided by other tools in other telespaces, you (currently) must hold a strong reference to the tool in which the DMD lives and the telespace in which that tool lives, to ensure that the both the tool and telespace do not get unloaded.

Groove has caching algorithms that periodically unload tools and telespaces to help efficiently manage memory usage - but any tools and/or telespaces that have strong references held on them will prevent such unloading. Obviously this means that the memory usage will not go down until the strong references on the tools and/or telespaces are released.

Wed, 21 Aug 2002 13:52:30 GMT

Use CreateDelta instead of OpenTransaction(false) for write operations

Many of you are familiar with the following pattern/style of code:

     var pITelespace = PropertyList.OpenProperty(PROPERTY_TELESPACE).Telespace;
     var pITransaction = pITelespace.OpenTransaction(false);
     try
        {
         .
         pIRecord.SetField("Name", "Paresh");
         pIRecord.SetField("Company", "Groove Networks");
         .
         pITransaction.Commit();
         }
   catch
         {
         pITransaction.Abort();
         }

There are 2 problems with this pattern/style of coding:

1) There will be 2 deltas disseminated to all other endpoints (which is less efficient)
2) Any undo/redo of the operations for Dynamics sequencing will not treat the 2 deltas as one transactional command.

Since the intent of the code above is to group all of the write operations as one transactional command, the appropriate approach is to have Dynamics Manager govern the execution of the write operations. This is accomplished by using the CreateDelta method:

   var pIDynamicsManager =
              PropertyList.OpenProperty(PROPERTY_DYNAMICS_MANAGER).DynamicsManager;
   var pIDelta = pIDynamicsManager.CreateDelta();
   try
      {
      .
      pIRecord.SetField("Name", "Paresh");
      pIRecord.SetField("Company", "Groove Networks");
      .
      pIDelta.Commit();
      }
   catch
      {
      pIDelta.Abort();
      }

Wed, 21 Aug 2002 13:12:23 GMT

Use shared object tables to hold sets of data with GrooveRunTimeData

Shared Object Tables are process wide object tables that can be used to store references to scalar or object types. They can be created with or without a developer specified name, but keep in mind that if a name is used, developers must think about other instances of their tool running on the same device (cross account/telespace/tool)

[code fragment for performing deletion of records in recordset]
   // Create shared object table that will use record ids as index and record
   // types as values. This shared object table will be primarily used to
   // provide information about a record upon receipt of asynchronous
   // deletion notifications
   var pISharedObjectTable = GrooveScriptFunctions.OpenSharedObjectTable("");
   GrooveRunTimeData.SetItem("DeletedRecordSharedObjectTable", pISharedObjectTable);

   // Get record and clone it
   var pIRecord = RecordSetEngine.OpenRecord(i_ID);
   var pIDeletedRecord = pIRecord.Clone();

   // Add cloned record to shared object table
   var pISharedObjectTable = GrooveRunTimeData.GetItem("DeletedRecordSharedObjectTable");
   pISharedObjectTable[i_ID] = pIDeletedRecord;

   //    Remove record from recordset
   RecordSetEngine.RemoveRecord(i_ID);
   .
   .

[code fragment from OnRecordSetChanged asynchronous event handler]
   case GrooveRecordSetChangeType_Removed:
      {
      // Get record id
      var RecordID = i_pIRecordIDEnum.OpenNext();

      // Get cached reference to record
      var pISharedObjectTable = GrooveRunTimeData.GetItem("DeletedRecordSharedObjectTable");
      var pIRecord = pISharedObjectTable[RecordID];

      // Remove cached reference to record
      pISharedObjectTable[RecordID] = null;
      .
      .

Tue, 20 Aug 2002 12:57:12 GMT

Sprinkle ASSERTs in your code when debugging free-threaded script code instead of breakpoints

Often you will find that it is difficult (if not impossible) to set breakpoints in free-threaded script code - I haven't figured out why yet. I have found that by placing the statement "GrooveDebugFunctions.Assert(false, "");" at the location I would have normally set the breakpoint, that the script debugger (Visual Interdev in my case) always comes up and allows me to debug my code.

Mon, 19 Aug 2002 13:05:18 GMT

Explicitly ask for an interface after getting it from PropertyList

When the PropertyList is used from script code to get an interface, one must keep in mind that the default IDispatch interface is returned from such a request, and in some cases this means you will not get the interface you asked for. For example:

   // The following line will get an IGrooveAccount interface
   var pIAccount = PropertyList.OpenProperty(PROPERTY_ACCOUNT);

   // The following line will also get an IGrooveAccount interface,
   // but this is not what you would expect
   var pITelespaceProvider = PropertyList.OpenProperty(PROPERTY_TELESPACE_PROVIDER);

   // This is the recommend way for both to make sure the expected
   // interface is returned
   var pIAccount = PropertyList.OpenProperty(PROPERTY_ACCOUNT).Account;
   var pITelespaceProvider =
      PropertyList.OpenProperty(PROPERTY_TELESPACE_PROVIDER).TelespaceProvider;

Mon, 19 Aug 2002 12:50:42 GMT

Use the "GrooveTelespace" object as reference to a tool's telespace

Starting with Groove v2.1, whenever you are using the free threaded version of the ScriptHost to write script code for your tool, you can now write code like:

   var pITransaction = GrooveTelespace.OpenTransaction(true);

        - instead of -

   var pITelespace = PropertyList.OpenProperty(PROPERTY_TELESPACE).Telespace;
   var pITransaction = pITelespace.OpenTransaction(true);