Download document

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
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
COM
APIs
StarTeam
SDK
Java
Library
Java
VM
Client
App
JNI
StarTeam
SDK
Java
Loader
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 appspecific 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 Javato-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
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.
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 crosscompiled 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 .NETfriendly façade over the J# APIs.
“C# APIs” - more useful for C# or Visual Basic
.NETprogrammers.
Client App 1
StarTeam SDK
for .NET
C#
Source Code
Borland.StarTeam
C#
Edge Code
Client App 2
J#
Source Code
Borland.StarTeam.Core
Java / J#
Core Code
J#
Edge Code
Targeting .NET
Writing Core Applications in J#.
Writing Native Applications in C#.
Writing Core/Edge Applications.
Writing .NET
Applications in J#
Writing .NET Applications in J#
Core apps written in Java and crosscompiled 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#
Client App
Java / J#
Core Code
Borland.StarTeam.Core
Java / J#
Core Code
J#
Edge Code
Writing .NET
Applications in C#
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.
Client App 1
Writing .NET
Apps in C#
C#
Source Code
Borland.StarTeam
C#
Edge Code
Borland.StarTeam.Core
Java / J#
Core Code
J#
Edge Code
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
Writing Core/Edge .NET
Applications
Core business logic written in Java, crosscompiled 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
C#
Edge Code
ClientApp.dll
ClientApp.exe
Borland.StarTeam
C#
Edge Code
StarTeam.Core
Java / J#
Core Code
J#
Edge Code
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 …
[email protected]