Windchill API

[MatthewHoover]

I have struggled with the API/Documentation of windchill's code since I started working with Windchill 9.1.

Maybe i have missed something along the way. The API that is supplied by PTC is lacking at best. It misses some of the main functions that are needed in order to do any deep customization. It leaves out many of the Beans for JSP editing as well as other main packages.

It is almost better to just start guessing in eclipse\NetBeans as to what package may help solve this issue. If all else fails you can try and put a tech support call that may help resolve the issue, but it seems they are in the same boat. Guessing until they give up and say it cant be done, only to find out later that it can infact be done by some "unsupported" method.

The rose model has helped me in places and is a better representation of the code(diagrams as to what links to what) but it still lacks the API feel. It cannot be easily search(in IE) and can be a lengthy process if you are just taking shots in the dark.

It does, however, gives a basic idea of what fields are contained in that item type and is better than the API for the most part, but it only covers the wt folder. While this is the main portion of the coding there are many important methods in the com folder it leaves out. Also in an IDE you can find this same information out just as quickly.

I have to be missing something. Where is the real API? The one the coders at PTC must be using.

Has anyone come across such documentation? Is there a free third party website that i have overlooked?

Any information as to the lost API would be helpful.

Thanks

[ddemay]

Well the quickest way is to license information modeler and rational rose.

I wrote something that creates a full javadoc using introspection of every class in codebase and all jars required. It list all methods, public, private, protected, and any constants. It tracks inheritance,etc. The idea then is this data would be polished to javadoc like documentation using XSLT to make it nice with CSS and URL's between docs created per class. This utility still needs a bit of finishing, but anyone who google how to create an xml file using java, introspection, a little creativity and sweat can build a full javadoc not supplied by PTC.

It works on any java code.

I was going to take it one step further and say for those that are persistables, list the queryspec to db column name equivalency, but just not had time to work on it.

If I finish it, I could publish the utility, but not the result of the utility as its PTC's code.

I can share the unfinished utility if interested and you are willing to help me get it completed.

I have sat on it for the past year.

Dave

Sent from my Verizon Wireless BlackBerry

[jessh]

Using any class, method, of field, not in the PTC supplied Javadoc is
not supported. Technical support cannot be of much help with any
customization done using such access and any such customization may
break at /any /time (e.g. even with a temp patch).

PTC is committed to the documented, supported APIs functioning and
continuing to function -- complete with a deprecation notice long (2
major releases as I recall) in advance to any API being removed. All
other APIs can be removed or changed in /any /fashion at /any /time,
though. If all APIs were considered supported, then R&D's hands would
be tied when issues are found that require changes like refactoring.
Also, there is no way all API's could be sufficiently well documented,
known/supported by technical support, etc. Most any large application
or library has APIs intended only for internal use -- Windchill is by no
means an oddity in this respect.

The technique Dave suggests below would simply give you all class,
method, and field signatures -- but no real /documentation /on any of
these. Any static analysis tool (including IDEs to some degree) can
give you such information, albeit not in Javadoc form. This misses the
distinction between supported and unsupported APIs, which really is
critical. It also lacks any further commentary on how APIs are to be
used, what they do, etc.

That all raises 2 basic issues:

1. Are there enough supported APIs to accomplish desired/necessary
customizations in all areas?
2. How well documented are the supported APIs in PTC's Javadoc and
documentation in general?

There is certainly room for improvement in both areas. If you run into
shortcomings in these areas, then all I can suggest is filing an SPR
with technical support to fill the API gap or improve the
documentation/Javadoc as needed.

Finally, PTC R&D /does/ use the supported APIs to develop the product.
The supported APIs are not some second-class set of APIs only for use in
customization. PTC R&D /additionally /uses unsupported APIs, of course
-- but as already noted supporting all APIs for use in customization is
simply not workable.

--
Jess Holle

P.S. I've certainly attempted to do my part on these issues. I try to
ensure that sufficient APIs are supported and well documented in my
areas. That's not to say I may not have fallen short -- but I certainly
have been mindful of customization needs when adding or changing APIs.

[MatthewHoover]

I understand that these methods are not supported. However, simply stating that the the top of the method or class lets me know: WARNING! these are not supported(the same thing i see now). BUT the programmer is sitting there writing the method, he passes in 6 strings sometimes and in the method callous they are this:
method(string, string1, string2, string3, string4, string5)throws WTException

Now PTC has done a good job at naming there methods which helps A LOT, not naming them cryptic random things makes me happy but the parameters can still be a little strange to me at times.

Okay now i know this is an unsupported method(above), I know i am using at my own risk. It would now take the coder, 30 seconds-2 minuets at most to properly document and explain what this code does and maybe say again this is unsupported method, but still allow me to save me anywhere form 10 minuets to an hour trying to figure out what he did.

I am not asking PTC to support every method they use, I realize that is pretty unrealistic, but simply telling me what the method does and what they call outs are for doesn't seem like that big of a stretch. The coders are already there making the method. Why not spend the extra few seconds to save customers from the frustration?

Stick these unsupported methods java docs in a different location that the current supported Java docs maybe?

[jessh]

Documenting unsupported methods in /any /fashion whatsoever would be
rather counterproductive. It's not just that PTC does not provide
support for using them, it's really the intent that unsupported methods
only be used by PTC R&D. [If Java 8's module system had been around
when the APIs were created it likely would have been used to make these
methods uncallable outside PTC's code modules.] Providing any level of
documentation on them would only encourage their use, which PTC
certainly does not wish to encourage or condone.

If there is no /supported/ method to accomplish what you need or the
documentation for the supported methods is insufficient, then file an
SPR and work with technical support to get a resolution. Opting to go
ahead and use an unsupported method instead is a really bad idea -- and
not one PTC should facilitate in any way.

--
Jess Holle

[Again, this is my opinion, not a statement for my employer.]

On 1/9/2011 6:51 PM, Hoover,Matthew,IRVINE,R&D wrote:
> I understand that these methods are not supported. However, simply stating that the the top of the method or class lets me know: WARNING! these are not supported(the same thing i see now). BUT the programmer is sitting there writing the method, he passes in 6 strings sometimes and in the method callous they are this:
> method(string, string1, string2, string3, string4, string5)throws WTException
>
> Now PTC has done a good job at naming there methods which helps A LOT, not naming them cryptic random things makes me happy but the parameters can still be a little strange to me at times.
>
> Okay now i know this is an unsupported method(above), I know i am using at my own risk. It would now take the coder, 30 seconds-2 minuets at most to properly document and explain what this code does and maybe say again this is unsupported method, but still allow me to save me anywhere form 10 minuets to an hour trying to figure out what he did.
>
> I am not asking PTC to support every method they use, I realize that is pretty unrealistic, but simply telling me what the method does and what they call outs are for doesn't seem like that big of a stretch. The coders are already there making the method. Why not spend the extra few seconds to save customers from the frustration?
>
> Stick these unsupported methods java docs in a different location that the current supported Java docs maybe?

[ddemay]

I for one know tricks like using the com.ptc.xxxx.xxx packaging for my java code gives me certain productive advantages. If the method is not private, it's fair game for the most part. There has been the occassional class file I have not been able to reverse engineer. The ultimate end point of this topic is that PTC isn't responsible for us to know beyond the basics how their tool works. Customer or no customer. There are those like myself out there that just look for job security in knowing as much as possible and thus will invest time in figuring out things when not getting a paycheck to do so. Throwback a few beers and cheetos and off I go into the neverland called Windchill API.



Sent from my Verizon Wireless BlackBerry

[tbusch]

This doesn't easily solve the problem, but it can lead you to the understanding you desire:

Get a good decompiler plugin for Eclipse and bring the Windchill codebase in as a referenced folder or library. Then, throw a method call in your class and tap F3 -- this will take you to the decompiled implementation, assuming the decompiler was able to decipher it.

I will warn you in advance that diving in to PTCs code like this is more than enough reason to seek therapy within 24 hours. It can be mind boggling, to say the least. For example, I haven't had enough patience to figure out how they implemented the code that supports most Info*Engine Webjects...

-Thomas R. Busch
Sr. Software Developer
Stryker Instruments
(269) 323-7700 x4014
tom.busch@stryker.com

[jessh]

I understand and respect the desire for a customizer to know as much as
possible about what's going on in Windchill's code. [I'm the same way
with JVM code, for instance.]

In that regard, it has often occurred to me that providing the full
source upon demand would be really nice for customizers. On the other
hand, there are issues with this:

1. Even if NDA's, etc, are required there are concerns about
intellectual property "migration"
2. There are serious concerns about customizer's using this source
"appropriately".

Setting aside #1 entirely, #2 by itself suffices to convince me that
Windchill customizer's really shouldn't have the full source.

Why?

Your response exemplifies one of the primary concerns: that customizers
would use information about unsupported APIs to call those APIs. That
is precisely what should /never /be done even if one had all of the
source code. In cases this can do more than put a customization's
functionality at risk, but instead risk overall system stability. It
also makes it impossible for R&D to do the right thing. Where the
supported APIs are insufficient, R&D needs to know this and to make
appropriate APIs supported -- thus allowing them to know what is
available for use externally and to act accordingly.

The other big concern is similar: customizers might use information
about system internals to determine how they operate, assume that
they'll continue operating this way, and build customizations upon these
assumptions. This is very dangerous in that R&D is free to change any
of this at any time. Where the documentation is insufficient, R&D needs
to know this and provide documentation -- thus allowing them to know
what behavior they've committed to maintaining for customizers.

Going "out of bounds" by calling unsupported APIs, relying on details
determined from decompilation, and so forth also greatly increases the
risk for moving the system forward to new MORs and versions -- thus
putting both the customer and PTC behind the 8-ball. Clearly PTC should
do all it can to help customers avoid this situation.

--
Jess Holle

[jessh]

For use of unsupported APIs, in general, your approach of using unit
tests, wrapper APIs, etc, seems like the sanest if you *must* do this.

I strongly encourage filing and pushing SPRs on all gaps in the
supported APIs, though. I'm realistic enough to realize that in some
cases where such an SPR remains unresolved you need to move on and
implement functionality any way you can. Hopefully in some such cases
you'll re-evaluate the ROI of the customization in question and decide
that its not worth using an unsupported API. Without an SPR and a
continued push on it, however, there is no good way for product
management, technical support, or R&D to know about the gap or its
import to real customer use cases. Sure, we should foresee everything,
but realistically we can't -- and without this form of feedback nothing
can improve.

--
Jess Holle

[MatthewHoover]

I too also like to find everything I can about the code.For my own benifits and to share knowlege with others.

I would not expect PTC to provide source code, I can only imagine all the strange and random things that people would mutate Windchill to be.

Without using unsupported methods Windchill work flow expression robots would be over very little use to me and customization of JSPs would be all but out the door.

getTypeNameFromTypePicker(NmCommandBean) is unsupported, and HIGHLY useful. I understand the need to file SPR's for these methods to bring about visiablitly but i would spend an hour a day asking for new methods when PTC has already created them. AND if the SPR is unresolved i just waited killing valuable production time waiting to hear this.

I have not had a chance to look to deeply into 10 but i am assuming it was left open to configurations. Without being able to touch the unsupported methods reserved for R&D it is not as configurable of a product. Leaving all customizations only open to PTC?

[jessh]

On 1/10/2011 10:37 AM, Matthew Hoover wrote:
>
> I too also like to find everything I can about the code.For my own
> benifits and to share knowlege with others.
>
> I would not expect PTC to provide source code, I can only imagine all
> the strange and random things that people would mutate Windchill to be.
>
> Without using unsupported methods Windchill work flow expression
> robots would be over very little use to me and customization of JSPs
> would be all but out the door.
>
> getTypeNameFromTypePicker(NmCommandBean) is unsupported, and HIGHLY
> useful. I understand the need to file SPR's for these methods to bring
> about visiablitly but i would spend an hour a day asking for new
> methods when PTC has already created them. AND if the SPR is
> unresolved i just waited killing valuable production time waiting to
> hear this.
>
> I have not had a chance to look to deeply into 10 but i am assuming
> it was left open to configurations. Without being able to touch the
> unsupported methods reserved for R&D it is not as configurable of a
> product. Leaving all customizations only open to PTC?
>
I don't think R10 is any more restricted than any previous release in
this regard.

The intent is certainly not to prevent or limit customizations by others
-- PTC field personnel shouldn't be using unsupported APIs any more than
anyone else.

If no one invests any of their time filing SPRs for what they need, then
the situation will not improve. I know I end up spending a fair amount
of time on such interactions with my "library vendors" -- ranging from
the JVM itself to various other library producers. Spending the time
may well not get the issue resolved in time for your current project,
but maybe for the next. Otherwise, PTC cannot help if they do not know
where help is needed.

--
Jess Holle

[ddemay]

It just means, plain and simple, you are on your own. What hasn't been said
is *sometimes* it is possible to pull code from earlier releases to maintain
backward compatibility. Especially if all it does is query and prepare data
the way you want. i.e a case might be a class is refactored or renamed. If
a newer version of same class exists, but the method does not, then you need
to think it through. The response you posted earlier on the team question
is a good thing to point out. Many 'Helper' classes like TeamHelper exist
and wind up called a StandardxxxxxxxxService class method. That alone allows
you to search the code and packages for these. Most are basic queryspec
functionality.



All said, there are many classes that just never change. The tool doesn't
change enough to warrant changing them. Your basic queryspec, queryresult
and persistencehelper type of code has not changed since 6.2.6. That is
true for quite a lot of other code. You get however an occasional big
change to fairly standard code such as when moving from 8 to 9 and change
objects went from managed interface to indirectly implementing Versioned and
possessing a VersionIdentifier. Given the fair warning time you have
considering more then just the code changes it takes to upgrade a system,
there is usually PLENTY of time to fix any issues with code between
upgrades.



The only sage advice I can give is this. NEVER and I mean NEVER put
unsupported API code directly into a workflow or transition in a workflow.
If you must invoke it do so from your own wrapper class external to the
workflow.