4128 Targeting Java, COM and.NET with the StarTeam SDK Ron Sauers Principle Architect Borland Software Corporation

Java or.NET? Why not target both platforms? Important to allocate resources to maximize customer benefits with each new product release. StarTeam SDK: we strive to support Java, COM and.NET equally well. Share as much source code across platforms as possible. Building separate implementations for different platforms only when there is no good alternative, or when there is significant customer benefit.

Overview Our Core/Edge approach. Targeting COM. Targeting.NET.

The Core/Edge Approach

Share as much design and implementation across platforms as possible. Build separate implementations for different platforms only when there is no good alternative, or when this results in significant customer benefit. “Core” code: shared across all platforms. “Edge” code: platform specific.

The Core/Edge Approach Common Core Code Platform1 Edge Code Platform2 Edge Code

Goals and Constraints The core/edge approach makes sense only if most of the implementation is core. Edge pieces must be small and manageable. Spend more resources on new features and less on porting. App developers should not suffer from our choice of implementation strategy. Each flavor of the SDK should feel as if it were designed natively for that platform.

Our Strategy SDK Core: written using the subset of Java that is also compatible with Microsoft Visual J#.NET. Java APIs: Since the core code is written in Java, the Java APIs are easy. When we use features of Java that are not also supported by J#, that becomes Java edge code.

Our Strategy: COM COM APIs: thin wrappers implemented using the Microsoft Active Template Library (ATL). Wrappers invoke Java APIs through the Java Native Interface (JNI). COM edge code: loads and initializes the Java VM; gets handles to Java classes and methods; marshals data types between the COM and Java; etc.

Our Strategy:.NET.NET APIs: Core code cross-compiled to.NET using Visual J#. Edge code written in J# replaces the corresponding Java edge code. Edge code written in C# provides a façade that presents a more natural.NET API. For example: properties, indexers, collection classes and other.NET types, native.NET event model, and so on.

What is Core Code? That subset of Java that is also 100% compatible with Microsoft Visual J#.NET. Avoid J# extensions that allow it to better integrate with the.NET environment (for example, ubyte). J# extensions expressed as comments are OK. For example: custom attributes. J# runtime libraries: equivalent to Java 1.1.5, plus Java 1.2 collection classes.

What is Edge Code? References to features that were added to the Java class libraries in 1.2 or later. Parsing or manipulation of XML. References to third-party class libraries. References to and/or implementation of native classes in a Win32 DLL. COM wrappers, implemented using ATL. NET includes edge code to provide a more natural.NET API.

XML Parsing Both Java and.NET support Document Object Model (DOM) Level 2 Core APIs. As of Java 1.4, the org.w3c.dom package is included in the Java runtime libraries. In Microsoft.NET, System.Xml provides equivalent functionality. Different package, class and method names. XML utilities in StarTeam SDK 2005.

Native Methods Java: uses the Java Native Interface (JNI) J#: describes calling conventions via custom attributes. If the native library is your own, it is possible in some cases to implement the JNI and J# native methods such that the method declarations can be core code. Another option: re-implement.NET edge code using classes in the.NET runtime libraries. Good for accessing Win32 features that are not available in the Java libraries.

Benefits of Re-Factoring Benefits of core/edge strategy are greatest when a high percentage of the code is core, and the edge code for each platform is small enough to be manageable. Existing code can be re-factored to better isolate the platform-specific parts of the implementation. Weigh the cost of re-factoring against the cost of maintaining two implementations of the extra edge code.

Least Common Denominator? Core/Edge is not the same as writing to the least common denominator of the two platforms. Make a conscious decision that the benefits of using a platform-specific feature outweighs the cost separate implementations for each platform.

Is it Worth the Effort? Should you consider the core/edge implementation strategy for your own project? –Assess customer requirements, new feature requests, existing source code, available third-party libraries. –Estimate percentage of core code you could achieve. –Weigh the relative cost of alternative approaches. We believe that the core/edge strategy has allowed us to apply our resources much more effectively than would have otherwise been possible.

Targeting COM

StarTeam COM APIs StarTeam SDK Java Library Java VM JNI StarTeam SDK Java Loader StarTeam COM APIs Client App

Targeting COM If you have a Java class library you want to expose through COM, there are a few SDK features that you can re-use. Native app must … –Locate the Java VM DLL. –Initialize the class path and library path with all the components required by the application. –Launch the VM, and obtain a handle to the JNI. Process is a trickier when your app requires the StarTeam SDK classes in addition to your own. StSDKLoader.dll provides several ways for a client app to drive the Java VM initialization process.

StarTeam-Certified Java VMs Each release of the SDK ships with a specific version of the Java VM. All StarTeam COM apps built with a given version of the SDK use the same “certified” VM by default. Certified Java VMs are installed in a private folder: [Program Files]\Borland\Java\ Each VM has a unique name: e.g. “Sun1.3.1_05” Each VM is installed in a separate subfolder.

Java.ini [Sun1.3.1_05] folder=Sun1.3.1_05 vendor=Sun Microsystems version=1.3.1_05 exe=bin\javaw.exe dll=bin\hotspot\jvm.dll

StarTeamSDK*.ini [Java VM] name=Sun1.3.1_05 classpath= librarypath= options= locale=

sdkapp.ini [Java VM] classpath=MyClasses.jar;%CLASSPATH%

StJavaConfiguration StJavaConfiguration - Enumerate the available Java VMs; select a given VM; load an sdkapp.ini; specify required Java libraries; register app- specific folders to be searched for classes and native DLLs. StJavaVMInfo - Describes a specific Java VM. Provides methods to manipulate the classpath, initialization options, etc. Also provides a way to run the VM. StRunningJavaVM - Describes the state of the currently running Java VM.

StInitializer StInitializer has a JavaConfiguration property. If you access the JavaConfiguration via StInitializer, then the StInitializer will automatically go through its normal SDK initialization sequence. The JavaConfiguration will already know about the StarTeam SDK's *.jar files, library path, etc. Client app then add its own components.

Obtaining a Handle to JNI Once the Java VM is loaded, Java objects are manipulated via the Java Native Interface (JNI). JNI defines a JavaVM data type that provides access to the running Java VM. If the VM is loaded via StSDKLoader, the JavaVM* is obtained via the JNI property of the StRunningVM object. With JavaVM*, the client app has full access to JNI.

Obtaining a Handle to a StarTeam Java Object If you are using the core/edge strategy, you will need to pass a StarTeam SDK object to app code written in Java. StarTeam COM objects support the ICoWrapper interface. gtujo(): get underlying Java object. Returns a jobject; this is the JNI handle to the underlying Java object. From the jobject, you can invoke any of the methods of the underlying StarTeam Java class. Do not to release our local reference to the jobject!

Alternative Approaches Require the Microsoft Java VM, and use the Java- to-COM features of Microsoft Visual J++. Both msjava and Visual J++ are obsolete technologies. If you have migrated your Java code to Visual J#, you can use the COM interop features of.NET. Both approaches require that your Java APIs be designed with the constraints of COM in mind: provide default public constructors; do not overload methods; etc.

Targeting.NET

StarTeam SDK for.NET is new for StarTeam Native.NET implementation, built using the core/edge strategy. Designed to support the development of core/edge client applications.

Implementation Strategies “Native”.NET applications –Written from scratch for the.NET platform. –Typically written in C# or Visual Basic.NET. “Core”.NET applications –Written to the StarTeam Java APIs –Cross-compiled to the.NET platform using Microsoft Visual J#. “Core/Edge”.NET applications –Core business logic is written in Java and cross- compiled to the.NET platform using Microsoft Visual J#. –Also have a native component (e.g., the GUI) written from scratch for the.NET platform.

Architecture of SDK for.NET Implemented using the core/edge strategy. Core code written in Java is cross-compiled to.NET using Microsoft Visual J#. Edge code written in J# replaces the corresponding Java edge code, as necessary. “J# APIs” – Virtually identical to Java APIs, most useful for client applications written in J#. Edge code written in C# provides a more.NET- friendly façade over the J# APIs. “C# APIs” - more useful for C# or Visual Basic.NETprogrammers.

StarTeam SDK for.NET J# Edge Code C# Edge Code Java / J# Core Code Borland.StarTeam.Core Borland.StarTeam C# Source Code Client App 1 J# Source Code Client App 2

Targeting.NET Writing Core Applications in J#. Writing Native Applications in C#. Writing Core/Edge Applications.

Writing.NET Applications in J#

Core apps written in Java and cross- compiled to.NET platform using Microsoft Visual J#. Use the J# flavor of the StarTeam.NET APIs, found in Borland.StarTeam.core.dll.

Writing.NET Apps in J# J# Edge Code Java / J# Core Code Borland.StarTeam.Core Java / J# Core Code Client App

Writing.NET Applications in C#

Native apps written from scratch for.NET. Usually written in C# or Visual Basic.NET. Use the C# flavor of the StarTeam.NET APIs, found in Borland.StarTeam.dll.

Writing.NET Apps in C# J# Edge Code C# Edge Code Java / J# Core Code Borland.StarTeam.Core Borland.StarTeam C# Source Code Client App 1

Namespace J# APIs: com.starbase.starteam C# APIs: Borland.StarTeam

Naming Conventions J# APIs: method names start with a lowercase letter. C# APIs: method names start with an uppercase letter.

Properties // J# APIs: get/set accessor methods. v = project.getDefaultView(); // C# APIs:Native.NET properties. v = project.DefaultView;

Indexers // J# APIs: get/set accessor methods. s = cr.get("Synopsis"); cr.put("Synopsis", "Just testing..."); // C# APIs: Native.NET indexers. s = cr["Synopsis"]; cr["Synopsis"] = "Just testing...";

Events J# APIs: events use the Java listener model. C# APIs: use native.NET events. No syntactic mechanism to provide parameters that refine the scope of interest. StarTeam event-handling APIs in.NET use EventSource objects similar to those used in COM. EventSource defines a delegate type that specifies the calling conventions of the corresponding event handlers.

Event-Handling in J# void listenForFilesAdded(View view) { Server s = view.getServer(); Type type = s.typeForName(s.getTypeNames().FILE); // Register an event listener with the view. view.addItemListener(new ItemAdapter() { public void itemAdded(ItemEvent e) { File file = (File)e.getNewItem(); System.out.println("File Added: " + file.getName()); }, type); // The type parameter refines the scope. }

Event-Handling in C# void ListenForFilesAdded(View view) { Server s = view.Server; Type type = s.TypeForName(s.TypeNames.FILE); // Create an event source via a factory method on the view. // The view and item type define the scope of interest. ItemEventSource source = view.NewItemEventSource(type); // Attach an application event handler. source.OnItemAdded += new ItemEventSource.Handler(OnFileAdded); }

Event-Handling in C# // The event handler. private void OnFileAdded( ItemEventSource source, ItemEventArgs args ) { File file = (File)args.NewItem; Console.WriteLine("File Added: " + file.Name); }

Collections J# APIs: return an array of objects. C# APIs: return an instance of a StarTeam-specific collection class (for example, ProjectCollection, ItemCollection, and so on). Collection classes are strongly typed. Implement IEnumerable, ICollection and IList. They are modifiable. Support searching, sorting, etc.

Collections // Collections are indexed by name, where appropriate. p = server.Projects["StarDraw"]; // Collections can be sorted easily. foreach (Label l in view.Labels.SortByID().Reverse()) {... }

Collections Collections support implicit cast operators for converting to an array of objects. For example: cast a Borland.StarTeam.ItemCollection to a Borland.StarTeam.Item[]. There are memory management issues to consider. If you are iterating over the members of a large collection, it is more efficient to use the.NET collection interfaces.

Collections // Allocates one C# wrapper object for every // member of the collection, simultaneously. Borland.StarTeam.ItemCollection c; Borland.StarTeam.Item[] items = c; for (int i = 0; i < items.Length; i++) { Item item = items[i];... } // Allocates one C# wrapper object at a time. Borland.StarTeam.ItemCollection c; foreach (Item item in c) {... }

Native.NET Types C# APIs use native.NET data types, where applicable. For example: File.CheckoutToStream() takes a System.IO.Stream, rather than a java.io.OutputStream. Some SDK types are also mapped to more appropriate.NET types: e.g.: OLEDate becomes System.DateTime; ItemList and Items both become ItemCollection.

Deprecated Classes and Methods Classes and methods that were already deprecated in the Java APIs are missing from the C# APIs. For example: VisDiff; swing utilities; the command-line classes; etc.

Writing Core/Edge.NET Applications

Core business logic written in Java, cross- compiled to.NET using Visual J#. Core code written to J# flavor of the StarTeam SDK APIs. User interface and other edge code typically written in C# or Visual Basic.NET. Edge code written to the C# flavor of the StarTeam SDK APIs.

Writing Core/Edge Apps J# Edge Code Java / J# Core Code StarTeam.Core C# Edge Code Borland.StarTeam J# Edge Code Java / J# Core Code ClientApp.dll C# Edge Code ClientApp.exe

Writing Core/Edge.NET Applications Client app's edge code (written to the C# APIs), must interoperate with app's core code (written to the J# APIs). For example: create a Borland.StarTeam.Server, and pass it as a com.starbase.starteam.Server. The StarTeam SDK for.NET was explicitly designed to support this scenario.

Converting from Edge to Core An object from the C# namespace can be implicitly cast to the corresponding type in the J# namespace. Borland.StarTeam.Project p1; com.starbase.starteam.Project p2 = p1;

Converting from Core to Edge Classes in the C# world include a static Wrap() method for wrapping the corresponding objects in the J# world. com.starbase.starteam.Project p1; Borland.StarTeam.Project p2 = Borland.StarTeam.Project.Wrap(p1);

Interface Adapters Each interface has a corresponding Adapter class to convert from an instance in the C# world to an instance in the J# world, and vice versa. Borland.StarTeam.ISecurableObject obj1; com.starbase.starteam.ISecurableObject obj2 = = new Borland.StarTeam.ISecurableObjectAdapter(obj1);

Java Adapters Adapters available for some Java types; see Borland.StarTeam.Util.JSharp. java.io.InputStream s1; System.IO.Stream s2 = new Borland.StarTeam.Util.JSharp.InputStreamAdapter(s1);

Dynamic Type Conversion If actual type of an object is not known until runtime, use dynamic type conversion services in the SDKWrapper class. // Convert a core object of unknown type // from the J# world to the C# world. object obj2 = SDKWrapper.Wrap(obj1); // Convert an edge object of unknown type // from the C# world to the J# world. object obj3 = SDKWrapper.Unwrap(obj2);

Questions?

Thank You 4128 Targeting Java, COM and.NET with the StarTeam SDK Please fill out the speaker evaluation You can contact me further at …