4128 Targeting Java, COM and 'NET with the StarTeam SDK

1
4128Targeting Java, COM and .NET with the
StarTeam SDK

• Ron Sauers
• Principle Architect
• Borland Software Corporation

2
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.
•  

3
Overview

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

4
The Core/Edge Approach
5
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.  

6
The Core/Edge Approach
7
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.

8
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.

9
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.

10
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.

11
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.

12
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.

13
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.

14
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.

15
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.

16
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.

17
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.

18
Targeting COM
19
StarTeam COM APIs
20
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.

21
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.

22
Java.ini

• Sun1.3.1_05
• folderSun1.3.1_05
• vendorSun Microsystems
• version1.3.1_05
• exebin\javaw.exe
• dllbin\hotspot\jvm.dll

23
StarTeamSDK.ini

• Java VM
• nameSun1.3.1_05
• classpath
• librarypath
• options
• locale

24
sdkapp.ini

• Java VM
• classpathMyClasses.jarCLASSPATH

25
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.

26
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.

27
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.

28
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!

29
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. 

30
Targeting .NET
31
Targeting .NET

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

32
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.

33
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.

34
StarTeam SDK for .NET
Client App 1
Borland.StarTeam
Client App 2
Borland.StarTeam.Core
Java / J Core Code
35
Targeting .NET

• Writing Core Applications in J.
• Writing Native Applications in C.
• Writing Core/Edge Applications.

36
Writing .NET Applications in J
37
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.

38
Writing .NET Apps in J
Client App
Java / J Core Code
Borland.StarTeam.Core
Java / J Core Code
39
Writing .NET Applications in C
40
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. 

41
Writing .NET Apps in C
Client App 1
Borland.StarTeam
Borland.StarTeam.Core
Java / J Core Code
42
Namespace

• J APIs com.starbase.starteam
• C APIs Borland.StarTeam

43
Naming Conventions

• J APIs method names start with a lowercase
  letter.
• C APIs method names start with an uppercase
  letter.

44
Properties
// J APIs get/set accessor methods. v
project.getDefaultView()
// C APIsNative .NET properties. v
project.DefaultView
45
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..."
46
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.

47
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. 
48
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)  
49
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)
 
50
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.

51
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())
     . . .  
52
Collections

• Collections support implicit cast operators for
  converting to an array of objects.
• For example cast a Borland.StarTeam.ItemCollectio
  n 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.

53
Collections
// Allocates one C wrapper object for every
 // member of the collection, simultaneously. Bo
rland.StarTeam.ItemCollection c Borland.StarTeam
.Item items c for (int i 0 i lt
items.Length i)      Item item
itemsi     . . .    // Allocates one C
wrapper object at a time. Borland.StarTeam.ItemCo
llection c foreach (Item item in c)      . .
.  
54
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.

55
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.

56
Writing Core/Edge .NET Applications
57
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.

58
Writing Core/Edge Apps
J Edge Code
Java / J Core Code
C Edge Code
ClientApp.dll
ClientApp.exe
Borland.StarTeam
StarTeam.Core
Java / J Core Code
59
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.

60
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.start
eam.Project p2 p1
61
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)

62
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.ISecurableO
bjectAdapter(obj1)
63
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.InputS
treamAdapter(s1)
64
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(obj
2)
65
Questions?
66
Thank You

• 4128
• Targeting Java, COM and .NET with the StarTeam
  SDK
• Please fill out the speaker evaluation
• You can contact me further at Ron.Sauers_at_Borland
  .com