RemObjects Blogs

Intro

RemObjects SDK is an awesome framework. Not only because its development feeds me and my 10 cats ;) but also because it allows to efficiently create applications on literally a dozen different platforms (to name them: Win32 (a.k.a. Delphi apps), desktop .NET framework, Windows Phone, Silverlight, Mono, Android, Android via MonoAndroid, iOS, iOS via MonoTouch, native MacOS X apps, Java and JavaScript). Unfortunately, it takes a bit of time to get started with developing, you can’t just jump right in. I myself (and most of the software developers I know) usually want to try their new, just downloaded toy without reading a ton of documentation pages.

So this article will try to be a kind of “crash course”. It won’t go very deep (there are Wiki articles on just about anything, if you want to delve in deeper, and our support team will help you with any questions), it will just try to give you some ‘feeling’ for the tech, a foothold to conquer the new framework.

This article covers the .NET version of the RemObjects SDK, however, the main approach will remain the same for all platforms (.NET, Xcode, Delphi, Java, JavaScript), so you won’t waste your time with this article, even if you don’t use .NET in your development work.

My colleagues will provide similar articles devoted to the other supported platforms later this month.

Note: This article covers the ‘Client Calls The Server’ scenario and doesn’t touch the ‘Server Pings The Client’ one. At this moment it is enough to know that the latter scenario is possible as well and its implementation won’t affect the former one.

The Core

The very heart of the RemObjects SDK is based on Channels, Messages, Envelopes and Services. Two more components used under the hood are Interfaces and Invokers. Don’t be afraid of these words, things are actually simpler than they look.

Let’s take a look at the ‘Client calls the server method’ scenario:

var methodCallResult = sampleService.DoSomething();

Looks simple, doesn’t it?

Here’s what happens from the RemObjects SDK’s point of view:

The client code calls the Foo method of some object serverService. Here, sampleService is an instance of the auto-generated proxy class, so calling the sampleService.DoSomething() method actually means the following:

1. Sending out a request
The Interface class serializes the request to the server using the configured Message. The Message is then wrapped by the attached Envelopes, if any are set up (f.e. data is encrypted somehow). Then the resulting data package is sent over the wire by the Client Channel.

2. Processing the request on the server side
The Server Channel retrieves the data package and pushes it to the Message component. Message unwraps it using the attached Envelopes, if needed. The resulting data package is provided to the Invoker, which reads the requested service, method names and method parameters from it.

Then the Service method is invoked, which does the actual job.

After the service method has finished, its result (or any exceptions occurred) are serialized, wrapped, and sent back over the wire using the Server Channel (yes, the processing pipeline is similar to step 1).

3. Retrieving the response
The Client Channel retrieves the data package, unwraps it and provides the serialized data package to the Interface‘s method that initiated the remote service call. This method then deserializes the provided data package and provides the method result back to the user code.

The magic is that the entire process is transparent for the user code on both ends of the wire and doesn’t require much attention from the developer. While the service method call pipeline might seem complicated (or even over-complicated), its performance overhead is negligible (especially for the binary serialization-based Message), making the actual network speed the main issue to care about, not the inner RemObjects SDK processes.

Sample Server

Let’s create a sample server and client app in a step-by-step guide and see how the Channels, Messages, Envelopes, Interfaces, Invokers and Services entities are implemented in a real RemObjects SDK-based application.

Prerequisites

For this tutorial you’ll need Visual Studio and either the RemObjects SDK for .NET or the Data Abstract for .NET frameworks installed. Also, a minimal knowledge of C# is required, but the same concepts would apply to Visual Basic for .NET, Oxygene or any other .NET language.

Server Application

As mentioned above, the server application should contain the Server Channel, Message, Envelope (if needed) and Invoker, as well as the Service itself.

1. Create a new Class Library project named BusinessLogic and add a single class to it:

using System;

namespace BusinessLogic
{
    public class StringProcessor
    {
        public Int32 Process (String value)
        {
            if (String.IsNullOrEmpty(value))
                return -1;

            return (value + @"Secret Salt").GetHashCode();
        }
    }
}

This project imitates an already existing implemetation of a real-world business logic method that should be exposed to remote client applications. While it is not necessary to put the business logic into a separate project, it was done here to emphasize that the business logic layer is fully separated from the to-be-implemented communication layer.

2. Add a new Windows Forms project to the solution and name it SampleServer. Of course, a real-world server application should be running as a Windows Service (and RemObjects SDK provides the needed application template), but for this “crash course” it will be easier to use the simple Windows Forms project.

3. Add the following references to the SampleServer project, as they provide the needed classes:

• RemObjects.InternetPack.dll
• RemObjects.SDK.dll
• RemObjects.SDK.Server.dll
• RemObjects.SDK.ZLib.dll

Also add a reference to the previously created BusinessLogic project, as we will expose its methods in the server.

4. Now we need to define the Server Surface Area, i.e. the service name, its methods, their parameters and return values, etc. This step is needed to allow the RemObjects SDK to generate strongly-typed Interface and Invoker classes.

Add a new ‘RemObjects SDK Service Definition’ item to the project.

A new file named NewLibrary1.RODL will be added to the project and the Service Builder app will be started automatically. The RODL is an XML file containing the service definition written in the ‘RemObjects Definition Language’ (or RODL), and the Service Builder provides the GUI to edit .RODL files without diving into the definition language syntax. Please note that the RemObjects SDK exposes the object model that allows to load, parse and generate .RODL files (and even to generate code based on these files), but this topic is outside the scope of this article.

As you can see, the file is almost empty. Select the single topic in the tree on the left side of the app’s window. The edit boxes that will appear will allow you to change the library name, set its namespace or even write its definition. Set the Library name to BusinessLogicLibrary.

A Library contains all the entities in the given RODL file. Consider it as a root of a service definition tree.

The next step is to define the Service. Press the ‘Service’ button (or right-click the Library name in the tree and issue the ‘Service’ context menu command) and rename the just added Service to BusinessLogicService. 

Now we can define this service’s methods. Press the ‘Add Operation’ button (the one with the green “+” glyph). A new method named ‘NewMethod’ will be added. Double-click its definition and change the method’s name to Process.

The last step is to define this method’s parameters and set its return type. Press the ‘Add Parameter’ button and change the parameter’s name to ‘value’. Change the parameter’s type to Utf8String (the ‘Data Type’ editor allows to select a type name from a combo box, so there is no need to enter it manually).

Set the Result type to Integer (the type name can be selected from the combo box as well).

If everything was done right, the Service Builder window should now look like this:

Close the Service Builder.

Set the ‘Build Action’ of the just added RODL file to ‘Embedded Resource’, so it will be embedded into the compiled application. You will find out why this is needed below.

5. As you can see, once you closed the Service Builder, three new code file were added to your project: BusinessLogicLibrary_Intf.cs, BusinessLogicLibrary_Invk.cs and BusinessLogicService_Impl.cs.
BusinessLogicLibrary_Intf.cs contains the Interface classes, BusinessLogicLibrary_Invk.cs contains the set of Invoker classes and BusinessLogicService_Impl.cs is a blank Service implementation class.
There is no need (and it is NOT recommended) to edit the code in the first two files.

In case you change the RODL file (for example add one more method to the service definition), the *_Intf and *_Invk files will be regenerated automatically to reflect the RODL changes. At the same time the _Impl file will stay untouched to prevent any code loss. Since the service implementation class contained in the _Impl file implements the service interface contained in the _Intf file, the service project won’t be able to build until the Service implementation class will match the Service definition.

For example: If you add a method to a service definition, the interface representing this service in the _Intf file will contain the new method definition as well. And because the Service implementation class has to implement this interface, the developer will have to add the corresponding method implementation to the service definition class.

6. Open the Service Implementation file (i.e. BusinessLogicService_Impl.cs) and find the Process method implementation. It is empty, so change it to

public virtual int Process(string value)
{
    return (new BusinessLogic.StringProcessor()).Process(value);
}

At this time, we have defined and implemented a Service (and it probably took more time for you to read the text above than to actually execute the steps in Visual Studio). Now we need to make the service available remotely.

7. Below, we will manually implement the network connectivity layer using the RemObjects SDK components. This is done to demonstrate the ins and outs of the framework as the RemObjects SDK provides the application templates and (starting from the May 2013 release) the pre-implemented NetworkServer class that allows to implement the connectivity layer in literally 3 lines of code.

Open the main form in designer mode (remember that our server app is intentionally primitive, so no properly layered architecture or ‘Run As Windows Service’ support here):
* Add the IpHttpServerChannel and BinMessage components to the main form (note that a licenses.licx file was automatically added to the server app project. Please do not delete this file).
* Open the properties of the IpHttpServerChannel component and open the custom editor for the Dispatchers property.
* Press the ‘Add’ button and select the previously added BinMessage instance as a value for the Message property.

* Press OK to close the dialog and save the property’s value.

That’s it. The server message processing pipeline (i.e. the Server Channel and Server Message) is set up.

8. Open the code-behind file of the main form and add this code line to the very end of the main form class constructor:

this.ipHttpServerChannel1.Open();

This code line will ‘open’ the server channel so it will start to accept the incoming connections.

Now you can start the server app. Open a web browser and go to the page http://localhost:8099/rodl. The server app will show the contents of the embedded RODL file at this address. Note that you can always set the the ’Embedded Resource’ property to None for the RODL file and the server will not advertise its methods.

Client Application

Even the most advanced server application is useless if there is no client application for it. So… let’s create one!

If you remember, a client application needs the following components implemented: Channel, Message, (possibly) Envelope and Interface. This may look scary again, but it will be much easier than it sounds.

1. Create a new Console Application (for simplicity reasons).

2. Add references to the assemblies

• RemObjects.InternetPack.dll
• RemObjects.SDK.dll
• RemObjects.SDK.ZLib.dll

These assemblies provide the client connectivity classes (as you can see, there is no need to reference the RemObjects.SDK.Server.dll assembly).

3. Now issue the ‘Add’ -> ‘Existing Item’ command (available via the context menu for the client application project entry in the Solution Explorer).

4. Select the BusinessLogicLibrary_Intf.cs file (it can be found in the server’s project folder) and add it as a link.

Adding the _Intf file as a link has a little but important advantage over simply adding an existing file to the client app project: when the server RODL is changed, the _Intf file is automatically regenerated. If this file is added as a link, there will be no need to update the _Intf file copy contained in the client app project.

This step adds the Interface part of the client app.

4. Add the following code to the Program.cs:

using System;

namespace SampleConsoleApplication
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.Write("Enter string: ");
            String value = Console.ReadLine();
            Console.WriteLine();
            Console.WriteLine("Processing...");

            // Communicating with the server
            SampleServer.IBusinessLogicService service = new SampleServer.BusinessLogicService_Proxy(@"http://localhost:8099/bin");

            Int32 hash = service.Process(value);

            Console.WriteLine();
            Console.WriteLine("String entered: {0}", value);
            Console.WriteLine("String hash: {0}", hash);
            Console.WriteLine("Press ENTER to continue...");
            Console.ReadLine();
        }
    }
}

The Console.WriteLine and Console.ReadLine calls here are pretty usual for any console application. Let’s take a closer look at these code lines:

// Communicating with the server
SampleServer.IBusinessLogicService service = new SampleServer.BusinessLogicService_Proxy(@"http://localhost:8099/bin");
Int32 hash = service.Process(value);

Here, a proxy for a server app service is created and then a service method is called (the Channel and Message components are automatically created behind the scenes to make this possible).

The IBusinessLogicService interface lists all methods exposed by the remote service, while the CoBusinessLogicService.Create static method creates a proxy class that implements this interface. This makes it possible to perform calls to a remote server transparently for the client app’s code.

5. There are probably some explanations needed regarding where the “http://localhost:8099/bin” URL came from. Let’s take a closer look on each part of the URL:

• http – Protocol used by the server channel. In this sample, we use a simple HTTP channel. The RemObjects SDK supports several other communication protocols as well (f.e. TCP-based ones).
• localhost – Name or IP address of the server’s host.
• 8099 – Port the Server Channel is listening to. 8099 is the default port for the IpHttpServerChannel used in our server application.
• bin – So-called dispatcher name. This is the name of the Message on the server side that processes the incoming data package. bin is the default name for the BinMessage.

6. Build and start both the server and client applications. Enter any string into the client application window and see the result returned by the server app:

Conclusion

At this point you should have a basic understanding of how the RemObjecs SDK-based communications can be implemented. As an exercise, try to add one more method to the Service and call it.

This article doesn’t cover many (or even most) of the RemObjecs SDK features. Server Events, Envelopes, client authentication processing and SSL support were not covered for simplicity reasons. Search our Wiki for the questions you are interested in. If for some reason you can’t find the info you need, don’t hesitate to call on our support via RemObjects Connect or email to support@remobjects.com.

Introduction

Today I’d like to write about a new technology that is currently being developed by the RemObjects team – the Remote Script Debugger.

The Remote Script Debugger is a service that exposes several methods and events. It has to be explicitly implemented by a server application (in most cases in the same way the DataService is implemented, i.e. without any custom code). The Script Debugger service was designed in a way that allows to easily add (or remove) it to an already existing DataAbstract for .NET server. You’ll literally have to write just one line of code that instantiates the Remote Script Debugger on the server side.
As you’ve probably noticed, the Remote Script Debugger is not just some client debugger application – it is a base service that exposes debug information about Business Rules Scripts being executed by the server.
In this blogpost, I’ll show you how to add a Remote Script Debugger service to a server application and create a really simple debugger application.

Server

Let’s create a simple Data Abstract for .NET server application using the New Project Wizard:

Use the PCTrade database as data source:

Don’t forget to add support for OData publishing – this will later allow to use a browser as data access application stub without writing any client application code.
Start the server and the open URL http://localhost:8099/odata/orders.
You should see some data in the server response (use the login/password ‘test’ when asked).

At this point, we have a working Data Abstract for .NET server. Now let’s add a debugger service to it.

Debugger Service
To add the Remote Script Debugger service, you need to perform the following steps:

1. Add a reference to the RemObjects.DataAbstract.Scripting.RemoteDebugger assembly.
2. Open your service’s .RODL file and change its base RODL from DataAbstract.RODL to RemoteScriptDebugger.RODL.
3. Add the ‘ScriptDebugger’ service and set its base service to the BaseScriptDebuggerService.
   
   
   
4. Close the Service Builder. _Intf and _Impl files will be regenerated and a new ScriptDebugger_Impl file will be added.
5. Open the ScriptDebugger_Impl file in the designer and point its ServiceSchemaName property to the same Schema the DataAbstract service uses.
6. Open the data service implementation code and make sure that the ‘Debug’ property of the EcmaScriptDebugger component is set to true.
7. Add a class override for the GetScriptDebugger method to the data service implementation:

   protected override RemObjects.DataAbstract.IScriptDebugger GetScriptDebugger() { return new RemObjects.DataAbstract.Scripting.RemoteDebugger.RemoteScriptDebugger(this.SessionID); }

   This change allows the Data Service to instantiate the script debugger and wire up its events.

8. Since the RemoteScriptDebugger uses events to send debugger data back to the client, you need to add EventSinkManager and MemoryMessageQueueManager components to your application. For Wizard-generated applications, the best place for network communication components is the Engine component. Don’t forget to set up the Message property of the newly added EventSinkManager component.
   
   
   

And that’s all that is needed to expose the Remote Script Debugger service. In a real-world appication you should add some security checks to control who can access the remote script debugger service.

Debugger Client

Now let’s create a very simple debugger application. You can add code highlighting or a better variable inspector window later, but to keep the debugger client application simple, I’ll skip these steps for now.

Create a new WinForms application. Add references to the Internet Pack for .NET, RemObjects for .NET and Data Abstract for .NET client assemblies, namely RemObjects.InternetPack, RemObjects.SDK, RemObjects.SDK.ZLib and RemObjects.DataAbstract.

You’ll also need to generate an _Intf file based on the RemoteScriptDebugger.RODL. Just open the file in the Service Builder and generate the Interface code using the CodeGen menu.

Now add 4 buttons, 2 Text Boxes and a ListView to the main form:

Several private fields have to be introduced:

private IClientChannel fChannel;
private IMessage fMessage;
private EventReceiver fEventReceiver;
private IBaseScriptDebuggerService fScriptDebugger;
private Guid fSessionId;

The main form of our application has to implement the IScriptDebuggerEvents interface to be able to retrieve data about debug events from the server.

Now let’s implement methods that send debugger commands (like Step Into or Continue Execution) to the server, and event handlers that are invoked when debugger events are sent by the server.

private void AttachButton_Click(object sender, EventArgs e)
{
  this.fChannel = new IpHttpClientChannel() { TargetUrl = @"http://localhost:8099/bin" };
  this.fMessage = new BinMessage();
  this.fEventReceiver = new EventReceiver() { Channel = this.fChannel, Message = this.fMessage };
 
  // Initialize ScriptDebugger service proxy
  this.fScriptDebugger = new BaseScriptDebuggerService_Proxy(this.fMessage, this.fChannel, "ScriptDebugger");
 
  // Attach Debugger
  this.fScriptDebugger.Attach(Guid.Empty, new String[] { "Enable Step By Step Debug" });
 
  // Assign ScriptDebuggerEvents listener
  this.fEventReceiver.RegisterEventHandler(this, typeof(IScriptDebuggerEvents));
}
 
private void DetachButton_Click(object sender, EventArgs e)
{
  this.fScriptDebugger.Detach(Guid.Empty);
}

Note how we attach to the debugger by calling the Attach method. Its first parameter defines which session data access calls should be debugged. An empty Guid means that it’ll listen (i.e. debug Business Rules Scripts) to all sessions.

It is possible to retrieve the session list from the server via the RemoteServiceDebugger service methods to be able to select specific session and debug scripts running in that context only.

The code behind the Step and Continue/Run buttons is quite straightforward:

private void StepButton_Click(object sender, EventArgs e)
{
  this.fScriptDebugger.StepInto(this.fSessionId);
}
 
private void RunButton_Click(object sender, EventArgs e)
{
  this.fScriptDebugger.Continue(this.fSessionId);
}

Look at the this.fSessionId parameter. This method requires an exact identifier of the session being debugged, and does not allow Guid.Empty as a wildcard. This restriction is due to the fact that Step, Continue or Break Execution commands can only be sent to specific data access sessions.

If the Guid.Empty wildcard was used, the Session identifier is sent by the server when any Business Rules Script method execution starts.

Now we need to implement event handlers for the FrameEnter, FrameExit, TracePoint, UnhandledException and Log events.

Each event is explained below, together with its handler implementation code.

• Log event: The most obvious event of all. It is fired when the log script method is called.

  public void Log(ScriptDebuggerEventSender sender, String message) { this.Invoke(new Action( delegate { this.LogTextBox.AppendText(String.Format("{0} {1}: Log: {2}\r\n\r\n", DateTime.Now, sender.ScriptName, message)); })); }

• FrameEnter event: Fired when a script function is entered. It allows to retrieve the script source code, the name of function being executed and the session ID of the client that triggered the event.

  public void FrameEnter(ScriptDebuggerEventSender sender, String functionName, String scriptSource, Boolean executionPaused) { this.fSessionId = sender.SessionID;   this.Invoke(new Action( delegate { this.ScriptSourceTextBox.Text = scriptSource; })); }

• FrameExit event: Fired when the debugger leaves the script method. In our sample application this event is not used, but in more advanced debbuger implementations, it would be a good place to remove current code line highlighting etc.

  public void FrameExit(ScriptDebuggerEventSender sender, String functionName) { }

• TracePoint event: The most important event of the RemoteScriptDebugger. It is fired before some script code line is executed and provides information about the position of the code being executed and the script variable values.

  public void TracePoint(ScriptDebuggerEventSender sender, ScriptDebuggerState debuggerState, Boolean executionPaused) { this.Invoke(new Action( delegate { this.LogTextBox.AppendText(String.Format("{0} {1}: Executing line {2}\r\n\r\n", DateTime.Now, sender.ScriptName, debuggerState.StartLine ));   this.VariablesList.Items.Clear(); this.ShowVariablesInfo(debuggerState); })); }

• UnhandledException event: Fired when script execution fails for some reason and Provides details about the exception that occurred.

  public void UnhandledException(ScriptDebuggerEventSender sender, ScriptDebuggerState debuggerState, ScriptExceptionType type, String message, String stackTrace) { this.Invoke(new Action( delegate { this.LogTextBox.AppendText(String.Format("{0} {1}: Failed at line {2}\r\n\r\n", DateTime.Now, sender.ScriptName, debuggerState.StartLine)); this.LogTextBox.AppendText(String.Format("{0} {1}: {2} {3}\r\n\r\n", DateTime.Now, sender.ScriptName, type, message));   this.ShowVariablesInfo(debuggerState); })); }

The ShowVariablesInfo method mentioned in the code above lists the script variable names and values. Variable values are serialized using the JSON serialization format. This allows to send variable values in a platform independent format.

The sample debugger application being created in this post uses this ShowVariablesInfo method implementation:

private void ShowVariablesInfo(ScriptDebuggerState debuggerState)
{
  for (Int32 i = 0; i < debuggerState.CallStack.Length; i++)
  {
    var frame = debuggerState.CallStack[i];
 
    ListViewItem item = new ListViewItem("[METHOD]");
    item.SubItems.Add(String.Empty);
    item.SubItems.Add(frame.FunctionName);
    this.VariablesList.Items.Add(item);
 
    foreach (var variable in frame.Variables)
    {
      item = new ListViewItem(variable.Name);
      item.SubItems.Add(variable.Type);
      item.SubItems.Add(variable.Value);
 
      this.VariablesList.Items.Add(item);
    }
  }
}

Now we need to add a simple Busness Rules Script to our server application. I’ll add a simple script code like:

function beforeGetData(names, requestInfos)
{
  log('Entering beforeGetData');
  log(JSON.stringify(session));
  log('Exiting beforeGetData');
}

Testing the debugger

Start the server again and open the URL http://localhost:8099/odata/orders.

Now start the debugger App and press the ‘Attach’ button.

Go back to the browser and reopen the http://localhost:8099/odata/orders.

You’ll see the script source and status messages in our debugger application (press the Step button to run the script in step-by-step mode).

That’s it. We have created a simple Business Script Rules remote debugger.

I intentionally skipped advanced parts, like code highlighting and the proper display of variable values (i.e. deserializing for JSON form), as these are far beyond the scope of this post.

Summary

This blogpost shows how you can easily add a Remote Script Debugger service to a Data Abstract for .NET based server application and how a simple debugger App can be created. Debugger application sources can be downloaded here.

The Script Debugger service is already integrated into Relativity server. Alex Karpenko is working on the integration of the Script Debugger into Schema Modeler and it looks really cool (expect a blogpost about Script Debugger soon).